Skip to main content

MCP Servers: When, Which, and How Many

Basic

Applies to: every FDE who uses a coding agent against a client's cloud and repos · Time to learn: 30 min reading + 15 min exercise · Lever: context

The Model Context Protocol (MCP) is the open standard that lets an agent call external tools and read external data. This page is about using MCP servers as a developer: which ones earn their place, how to install them, what each one costs in context, and how to keep them safe. If you are building MCP servers for a client, read Connect tools with the Model Context Protocol instead.

TL;DR
  • Use a docs MCP for the client's cloud so the agent reads current, authoritative docs instead of guessing flags from stale training data.
  • Start with three servers: a docs server, GitHub, and one memory or code-graph server. Add more only for a named job.
  • Every server costs context. Claude Code defers tool definitions by default (tool search), but a server you do not use is still noise, so turn it off per project.
  • Commit shared servers in .mcp.json. Put secrets in environment variables, never in the file.
  • Treat tool output as untrusted input: start read-only, use least-privilege tokens, and pin versions.

Why it matters in the AI age​

A model's training data is a snapshot. It is generic, it ages, and it knows little about the client's specific stack. When it does not know, it fills the gap with plausible text: a CLI flag that never existed, a service limit from two years ago, an API that was renamed. An MCP server fixes this by giving the agent a tool to look the answer up at the moment it needs it.

Problem without MCPWhat an MCP server changes
Stale or generic knowledge of a cloud service, SDK, or frameworkA docs server returns the current page or section on demand
Hallucinated flags, parameters, and limitsThe agent reads the authoritative reference and cites it
You copy and paste issue text, PR comments, or logs into the chatThe agent reads GitHub, the ticket system, or the cloud account directly
The agent re-reads the whole repo to answer structural questionsA code-graph server answers from an index (see Scratchpads, Memory, and Markdown Knowledge Bases)

Concrete example: ask for "the maximum size of a Lambda deployment package" or "the newest parameter of an API released last month". Without a docs server the agent answers from memory. With one, it searches the AWS docs, reads the page, and answers with the current number and the URL.

This lever is context: MCP is how the right facts reach the agent at the right moment. Too many servers work against the same lever, which is why this page also covers cost. See Context Engineering for the underlying mechanics.

Core concepts​

What MCP is (as of 2026-10)​

TopicFact
Current spec revision2026-07-28. The previous revision, 2025-11-25, is now the "Legacy" era that used an initialize handshake. In 2026-07-28 every request carries its protocol version.
Transportsstdio (a subprocess your client launches) and Streamable HTTP (HTTP POST to a single endpoint). The older HTTP+SSE transport is deprecated.
Server primitivesResources, Prompts, Tools
GovernanceAnthropic contributed MCP to the Agentic AI Foundation (AAIF) under the Linux Foundation, announced 2025-12-09 together with goose and AGENTS.md.
DiscoveryThe official MCP Registry is a preview "app store" for servers. Treat it as a directory, not a vetting service.

Remote (HTTP) servers add no local process and are what vendors host themselves. Local (stdio) servers run on your machine with your permissions, which matters for security below.

Tools, resources, and the context bill​

Each tool a server exposes has a name, a description, and a JSON schema. All of that is text the model must read. Claude Code (and other harnesses) reduce the bill with tool search: only tool names and server instructions load at session start, and full definitions are fetched when the agent needs them. Details are in How many servers.

How to do it​

Step 1: AWS Documentation MCP server​

The most useful server for most client work is the one for the client's cloud. For AWS, the open-source AWS Documentation MCP server (awslabs.aws-documentation-mcp-server, from the awslabs/mcp repo) runs locally and needs uv and Python 3.10 or newer.

ToolWhat it does
search_documentationSearches AWS docs; parameters include search_phrase, limit, product_types, guide_types (global partition only)
read_documentationFetches a docs page by URL
read_sectionsReads specific sections of a page (global partition only)
search_tableSearches a table on a page by section title and query (global partition only)
recommendSuggests related pages for a URL (global partition only)
get_available_servicesLists available services (China partition only)

Configuration from the server README, for any client that reads mcpServers JSON:

.mcp.json (project root)
{
"mcpServers": {
"aws-docs": {
"command": "uvx",
"args": ["awslabs.aws-documentation-mcp-server@<version>"],
"env": {
"FASTMCP_LOG_LEVEL": "ERROR",
"AWS_DOCUMENTATION_PARTITION": "aws"
}
}
}
}

The README example uses @latest. Replace <version> with the release you reviewed so the server does not change underneath you (see Security). The uvx tool@version form is documented by uv and accepts an exact version only.

The same server from the Claude Code CLI, built from the documented claude mcp add [options] <name> -- <command> [args...] syntax:

claude mcp add --scope project aws-docs \
--env FASTMCP_LOG_LEVEL=ERROR \
--env AWS_DOCUMENTATION_PARTITION=aws \
-- uvx awslabs.aws-documentation-mcp-server@<version>

Check it with claude mcp list or /mcp inside a session.

Example prompts that make the agent use it:

Use the aws-docs server to find the current maximum payload size for
API Gateway REST APIs. Quote the page URL.

Read the DynamoDB documentation on transactions and list the item and
size limits. Do not answer from memory.

I am writing a Terraform module for S3 Object Lock. Search the AWS docs
for the retention modes, then generate the resource using only
arguments confirmed in the docs.
The managed AWS MCP Server (as of 2026-10)

AWS announced general availability of the AWS MCP Server on 2026-05-06: a managed remote server that gives coding agents access to AWS services, part of the Agent Toolkit for AWS. AWS now recommends it over the older AWS API MCP Server and AWS Knowledge MCP Server, and says to remove those two entries from your client config to avoid tool conflicts. Its tools include aws___search_documentation and aws___retrieve_skill. It can also call AWS APIs with IAM credentials, so it is a write-capable server and needs the security care below.

Two authentication options, both documented by AWS for Claude Code:

# Option A: OAuth (needs IAM managed policy AWSMCPSignInOAuthAccessPolicy)
claude mcp add aws-mcp https://aws-mcp.us-east-1.api.aws/mcp --transport http

# Option B: SigV4 via the MCP Proxy for AWS (multi-account, read-only mode, default Region)
# Requires AWS CLI 2.32.0 or later and `aws login`
claude mcp add-json aws-mcp '{"type":"stdio","command":"uvx","args":["mcp-proxy-for-aws-cli@latest","https://aws-mcp.us-east-1.api.aws/mcp","--metadata","AWS_REGION=us-west-2"],"env":{}}'

AWS's decision guide: choose SigV4 when you need several accounts in one session, a read-only mode that hides write-capable tools, or a default Region. Choose OAuth for the simplest single-account start. In both cases the client's Region endpoint can differ from the AWS_REGION your operations target; check the AWS page for the list of eight supported endpoints.

How to choose between the two AWS options:

SituationPick
You only need current docs and the client forbids agent access to the accountAWS Documentation MCP server (local, no credentials needed)
You want docs plus guided AWS operations through IAMManaged AWS MCP Server, SigV4, read-only mode first
Your config still lists aws-api-mcp-server or aws-knowledge-mcp-serverMove to the managed AWS MCP Server and remove the old entries

I could not confirm in AWS's current setup page whether the managed server fully replaces the standalone Documentation server, so check the page linked in Sources before you swap one for the other on an engagement.

Other useful AWS Labs servers​

The awslabs/mcp repo hosts many servers; most install as uvx awslabs.<name>@<version>. Add one only when the task needs it.

ServerUse it for
awslabs.aws-iac-mcp-serverCloudFormation docs, CDK guidance, security validation (replaces the deprecated Cloud Control API server)
awslabs.eks-mcp-serverEKS cluster work
awslabs.dynamodb-mcp-server, awslabs.postgres-mcp-serverData modelling and queries; run read-only against non-dev data
awslabs.lambda-tool-mcp-serverExposing Lambda functions as tools

Step 2: Other docs servers​

ServerCoversEndpoint or packageNotes
Context7 (Upstash)Library and framework docs by library IDhttps://mcp.context7.com/mcp (remote), npm @upstash/context7-mcpFree API key sent as Authorization: Bearer .... Tools: resolve-library-id, query-docs.
Microsoft LearnAzure and Microsoft docshttps://learn.microsoft.com/api/mcp (remote)Tools: microsoft_docs_search, microsoft_docs_fetch, microsoft_code_sample_search. The official Claude Code route is the plugin /plugin install microsoft-docs@claude-plugins-official.
Cloudflare docsCloudflare referencehttps://docs.mcp.cloudflare.com/mcp (remote)Described as up-to-date reference information on Cloudflare.

Remote servers use the documented HTTP syntax claude mcp add --transport http <name> <url>. For example (built from that syntax and the endpoints above):

claude mcp add --transport http cloudflare-docs https://docs.mcp.cloudflare.com/mcp

claude mcp add --transport http context7 https://mcp.context7.com/mcp \
--header "Authorization: Bearer ${CONTEXT7_API_KEY}"

Run the Context7 command in a shell where CONTEXT7_API_KEY is set, and prefer the .mcp.json form below for shared config so the key stays out of the file. Always include "type": "http" for remote servers in .mcp.json; a GitHub issue on the Cloudflare MCP repo reports that omitting it makes Claude Code treat the entry as stdio and fail silently.

Step 3: GitHub​

The official GitHub MCP server (github/github-mcp-server) gives the agent issues, PRs, and repo contents. The documented Claude Code command for the local Docker server is:

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

The remote server at https://api.githubcopilot.com/mcp/ uses OAuth on first use on github.com. The server supports --toolsets, --tools, and --read-only options so you can expose only what the task needs. OpenCode's docs warn that the GitHub server tends to use many tokens, so restrict toolsets. If the gh CLI is installed and authenticated, it is often the cheaper choice (see the decision table).

Step 4: Memory and code-graph server​

Pick one. Details and trade-offs live in Scratchpads, Memory, and Markdown Knowledge Bases; the short version:

ServerStrength
DeusData/codebase-memory-mcpSingle native binary, local code knowledge graph, no API key. Reports about 10x lower token use than file-by-file exploration, at lower answer quality (83% vs 92% in its preprint).
oraios/serenaSymbol-level retrieval and editing through language servers
basic-memoryMarkdown notes the agent reads and writes, viewable in Obsidian (AGPL-3.0)

Step 5: Scopes and sharing​

Claude Code adds servers at one of three scopes with -s or --scope (default local):

ScopeLoads inShared via gitStored in
localcurrent project, only youno~/.claude.json
projectcurrent project, whole teamyes.mcp.json in the project root
userall your projectsno~/.claude.json

When the same server name exists in several places, local wins over project, then user. Commit .mcp.json for servers the whole team needs; Claude Code asks each person to approve project servers before first use, and claude mcp reset-project-choices resets those answers. Use ${VAR} or ${VAR:-default} expansion for URLs and secrets:

.mcp.json (committed)
{
"mcpServers": {
"aws-docs": {
"command": "uvx",
"args": ["awslabs.aws-documentation-mcp-server@<version>"],
"env": { "FASTMCP_LOG_LEVEL": "ERROR", "AWS_DOCUMENTATION_PARTITION": "aws" }
},
"context7": {
"type": "http",
"url": "https://mcp.context7.com/mcp",
"headers": { "Authorization": "Bearer ${CONTEXT7_API_KEY}" }
}
}
}

Other CLI commands: claude mcp list, claude mcp get <name>, claude mcp remove <name>.

OpenCode equivalent. OpenCode uses the mcp key in opencode.json, with type set to local or remote:

opencode.json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"aws-docs": {
"type": "local",
"command": ["uvx", "awslabs.aws-documentation-mcp-server@<version>"],
"enabled": true,
"environment": { "FASTMCP_LOG_LEVEL": "ERROR", "AWS_DOCUMENTATION_PARTITION": "aws" }
},
"cloudflare-docs": {
"type": "remote",
"url": "https://docs.mcp.cloudflare.com/mcp",
"enabled": true
}
}
}

Local servers take command (array), environment, enabled, and timeout; remote servers take url, headers, and oauth.

How many servers​

Every connected server adds text to the context window, and a crowded context degrades attention (see Context Engineering). The mitigation is a small set plus deferred loading.

MechanismWhat to know (Claude Code, as of 2026-10)
Tool searchOn by default: only tool names and server instructions load at session start; definitions are fetched on demand. Works with Opus 4, Sonnet 4, Haiku 4.5 and later; earlier models load all MCP tools upfront.
ENABLE_TOOL_SEARCHUnset means all MCP tools deferred. auto loads tools upfront while their definitions are under 10% of the context window. auto:N sets a custom percentage. false loads everything upfront.
alwaysLoadSet "alwaysLoad": true on a server in .mcp.json to exempt it from deferral. Use it only for a server the agent needs every turn.
Output limitsWarning above 10,000 tokens per tool result; default maximum 25,000 (raise with MAX_MCP_OUTPUT_TOKENS). Text over 50,000 characters is saved to a file.
Disable per projectToggle a server off in the /mcp panel; the choice is stored per project. claude mcp remove <name> deletes it.

Anthropic's engineering team shows why on-demand loading matters: in one example workflow, reading tool definitions on demand dropped usage from 150,000 to 2,000 tokens. That figure is one workflow, not a typical per-server cost; measure your own setup (see Context Engineering).

Starter set for an FDE:

  1. A docs server for the client's cloud (AWS Documentation MCP, Microsoft Learn, or Cloudflare docs).
  2. GitHub (or gh) for issues and PRs, with limited toolsets.
  3. One memory or code-graph server for unfamiliar, large repos.

Add Context7 when the client's stack leans on fast-moving libraries. Add a database or cloud-operations server only for a named task, read-only, and remove it when the task ends.

Security​

An MCP server runs code and feeds text into your agent's context. Both matter.

RiskWhat it looks likeWhat to do
Prompt injection via tool resultsA web page, issue, or doc contains instructions that the agent followsTreat all tool output as untrusted data; keep human approval on writes; do not combine untrusted-content tools with write-capable tools in one session
Tool poisoningA server's tool description hides instructions, or changes after you approved itUse servers from vendors you trust; the MCP spec says tool descriptions and annotations are untrusted unless the server is trusted; review diffs when you bump a version
Over-privileged tokensA broad PAT or admin IAM role behind a toolIssue the narrowest scope, per task, short-lived. The MCP security guidance warns against wildcard or omnibus scopes
Supply chainuvx pkg@latest or npx -y pulls new code on every startPin an exact version (pkg@1.2.3, --from 'pkg==1.2.3') and Docker images by digest; review third-party servers before use
Local server compromiseA stdio server runs with your user's permissionsPrefer remote vendor servers or containers; run with minimal default privileges
Shadow servers and secretsPersonal servers with client tokens, keys committed in .mcp.jsonKeep servers in reviewed .mcp.json; secrets only via ${VAR}

The OWASP MCP Top 10 (a living document) is a good checklist: MCP01 Token Mismanagement and Secret Exposure, MCP02 Privilege Escalation via Scope Creep, MCP03 Tool Poisoning, MCP04 Software Supply Chain Attacks and Dependency Tampering, MCP05 Command Injection and Execution, MCP06 Prompt Injection via Contextual Payloads, MCP07 Insufficient Authentication and Authorization, MCP08 Lack of Audit and Telemetry, MCP09 Shadow MCP Servers, MCP10 Context Injection and Over-Sharing.

Client data rules. Before you connect a server to a client system, confirm that the client's policy allows sending that data to your model provider and to any third-party MCP vendor. A docs server only sends your search query out; a database or ticket server sends client data into the model context. Use the client's own accounts and tokens, never personal ones, and revoke them at the end of the engagement.

Decision table: CLI tool, MCP server, or skill​

NeedBest fitWhy
Run git, gh, aws, kubectl, tofu with output you can pipeCLI toolZero context cost until used; the agent already knows common CLIs; easy to sandbox with permissions
Current docs for a cloud or libraryMCP server (docs)Search and fetch with structured results; no local install for remote servers
A live system with authentication and typed operations (GitHub, tickets, cloud account)MCP serverOAuth, typed schemas, and server-side limits such as read-only modes
A code index or persistent memory shared across sessionsMCP serverStateful service; the agent queries instead of re-reading files
A repeatable team workflow ("how we do a release", "how we write a migration")SkillLoaded on demand from files; versioned in git; no server to run (see Skills)
A rule that must always hold (format after edit, block secrets)HookEnforced, not advisory (see Hooks and Quality Gates)
Project facts the agent needs every sessionAGENTS.md / CLAUDE.mdAlways in context (see AGENTS.md, CLAUDE.md, and Rules)

Rule of thumb: if a good CLI exists and the agent can run it, use the CLI. Reach for MCP when you need current external knowledge, authenticated access with guardrails, or a stateful service.

Best practices​

  • Name servers by purpose (aws-docs, not server1) and keep the list in .mcp.json so teammates and CI agree.
  • Tell the agent when to use a docs server in AGENTS.md, for example "For AWS limits and API parameters, use aws-docs and cite the URL; do not answer from memory."
  • Ask for citations. A URL in the answer turns a docs lookup into something a reviewer can check.
  • Start every new server read-only and in a throwaway project; widen only after you have seen what it does.
  • Re-check the managed and standalone AWS servers when you start an engagement; this area changes quickly.
  • Check how much context a new server uses before you keep it (see Context Engineering).

Pitfalls to design around​

  • Keep one server per job: two servers that both search AWS docs confuse tool selection. Remove superseded entries (AWS says to drop the API and Knowledge servers when you adopt the managed one).
  • Pin versions in shared config; keep @latest for local experiments only.
  • Keep secrets out of .mcp.json; use ${VAR} references and the client's secret store.
  • Set "type": "http" on remote entries in .mcp.json.
  • Cap tool output with MAX_MCP_OUTPUT_TOKENS only when you need larger results; large results crowd out the task.
  • Do not assume a registry listing means a server is reviewed.

Try it​

Lab (15 min)

  1. In a scratch repo, run the AWS Documentation server command from Step 1 with --scope project and a pinned version.
  2. Ask: "What is the current maximum number of environment variables size for a Lambda function? Use aws-docs and quote the URL." Compare with the same question after claude mcp remove aws-docs.
  3. Add the GitHub server with a restricted toolset and compare how much context your session uses before and after.
  4. Open .mcp.json and confirm no secret appears in it.
  5. Write the three servers you would start with on your current client engagement, and why.

Checklist​

  • A docs MCP for the client's cloud is configured and the agent cites URLs
  • The starter set is no more than three to five servers
  • .mcp.json is committed and contains no secrets
  • Server versions are pinned; images pinned by digest
  • Tokens are least-privilege, short-lived, and the client's own
  • Write-capable servers (cloud, database) start read-only
  • Unused servers are disabled for this project
  • The client's data policy covers every connected server

Sources​