MCP Servers: When, Which, and How Many
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.
- 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 MCP | What an MCP server changes |
|---|---|
| Stale or generic knowledge of a cloud service, SDK, or framework | A docs server returns the current page or section on demand |
| Hallucinated flags, parameters, and limits | The agent reads the authoritative reference and cites it |
| You copy and paste issue text, PR comments, or logs into the chat | The agent reads GitHub, the ticket system, or the cloud account directly |
| The agent re-reads the whole repo to answer structural questions | A 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)
| Topic | Fact |
|---|---|
| Current spec revision | 2026-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. |
| Transports | stdio (a subprocess your client launches) and Streamable HTTP (HTTP POST to a single endpoint). The older HTTP+SSE transport is deprecated. |
| Server primitives | Resources, Prompts, Tools |
| Governance | Anthropic contributed MCP to the Agentic AI Foundation (AAIF) under the Linux Foundation, announced 2025-12-09 together with goose and AGENTS.md. |
| Discovery | The 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.
| Tool | What it does |
|---|---|
search_documentation | Searches AWS docs; parameters include search_phrase, limit, product_types, guide_types (global partition only) |
read_documentation | Fetches a docs page by URL |
read_sections | Reads specific sections of a page (global partition only) |
search_table | Searches a table on a page by section title and query (global partition only) |
recommend | Suggests related pages for a URL (global partition only) |
get_available_services | Lists available services (China partition only) |
Configuration from the server README, for any client that reads mcpServers JSON:
{
"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.
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:
| Situation | Pick |
|---|---|
| You only need current docs and the client forbids agent access to the account | AWS Documentation MCP server (local, no credentials needed) |
| You want docs plus guided AWS operations through IAM | Managed AWS MCP Server, SigV4, read-only mode first |
Your config still lists aws-api-mcp-server or aws-knowledge-mcp-server | Move 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.
| Server | Use it for |
|---|---|
awslabs.aws-iac-mcp-server | CloudFormation docs, CDK guidance, security validation (replaces the deprecated Cloud Control API server) |
awslabs.eks-mcp-server | EKS cluster work |
awslabs.dynamodb-mcp-server, awslabs.postgres-mcp-server | Data modelling and queries; run read-only against non-dev data |
awslabs.lambda-tool-mcp-server | Exposing Lambda functions as tools |
Step 2: Other docs servers
| Server | Covers | Endpoint or package | Notes |
|---|---|---|---|
| Context7 (Upstash) | Library and framework docs by library ID | https://mcp.context7.com/mcp (remote), npm @upstash/context7-mcp | Free API key sent as Authorization: Bearer .... Tools: resolve-library-id, query-docs. |
| Microsoft Learn | Azure and Microsoft docs | https://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 docs | Cloudflare reference | https://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:
| Server | Strength |
|---|---|
DeusData/codebase-memory-mcp | Single 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/serena | Symbol-level retrieval and editing through language servers |
basic-memory | Markdown 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):
| Scope | Loads in | Shared via git | Stored in |
|---|---|---|---|
local | current project, only you | no | ~/.claude.json |
project | current project, whole team | yes | .mcp.json in the project root |
user | all your projects | no | ~/.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:
{
"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:
{
"$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.
| Mechanism | What to know (Claude Code, as of 2026-10) |
|---|---|
| Tool search | On 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_SEARCH | Unset 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. |
alwaysLoad | Set "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 limits | Warning 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 project | Toggle 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:
- A docs server for the client's cloud (AWS Documentation MCP, Microsoft Learn, or Cloudflare docs).
- GitHub (or
gh) for issues and PRs, with limited toolsets. - 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.
| Risk | What it looks like | What to do |
|---|---|---|
| Prompt injection via tool results | A web page, issue, or doc contains instructions that the agent follows | Treat 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 poisoning | A server's tool description hides instructions, or changes after you approved it | Use 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 tokens | A broad PAT or admin IAM role behind a tool | Issue the narrowest scope, per task, short-lived. The MCP security guidance warns against wildcard or omnibus scopes |
| Supply chain | uvx pkg@latest or npx -y pulls new code on every start | Pin 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 compromise | A stdio server runs with your user's permissions | Prefer remote vendor servers or containers; run with minimal default privileges |
| Shadow servers and secrets | Personal servers with client tokens, keys committed in .mcp.json | Keep 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
| Need | Best fit | Why |
|---|---|---|
Run git, gh, aws, kubectl, tofu with output you can pipe | CLI tool | Zero context cost until used; the agent already knows common CLIs; easy to sandbox with permissions |
| Current docs for a cloud or library | MCP 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 server | OAuth, typed schemas, and server-side limits such as read-only modes |
| A code index or persistent memory shared across sessions | MCP server | Stateful service; the agent queries instead of re-reading files |
| A repeatable team workflow ("how we do a release", "how we write a migration") | Skill | Loaded on demand from files; versioned in git; no server to run (see Skills) |
| A rule that must always hold (format after edit, block secrets) | Hook | Enforced, not advisory (see Hooks and Quality Gates) |
| Project facts the agent needs every session | AGENTS.md / CLAUDE.md | Always 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, notserver1) and keep the list in.mcp.jsonso teammates and CI agree. - Tell the agent when to use a docs server in
AGENTS.md, for example "For AWS limits and API parameters, useaws-docsand 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
@latestfor 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_TOKENSonly 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)
- In a scratch repo, run the AWS Documentation server command from Step 1 with
--scope projectand a pinned version. - Ask: "What is the current maximum number of environment variables size for a Lambda function? Use
aws-docsand quote the URL." Compare with the same question afterclaude mcp remove aws-docs. - Add the GitHub server with a restricted toolset and compare how much context your session uses before and after.
- Open
.mcp.jsonand confirm no secret appears in it. - 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.jsonis 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
- Claude Code: Connect Claude Code to tools via MCP (syntax, scopes,
.mcp.json, tool search, output limits) - MCP specification (latest), transports 2026-07-28, versioning, security best practices
- Linux Foundation: formation of the Agentic AI Foundation (2025-12-09)
- Official MCP Registry
- AWS Documentation MCP server README and awslabs/mcp
- Setting up the AWS MCP Server (AWS docs)
- AWS MCP Server general availability, 2026-05-06
- Context7, Microsoft Learn MCP, Cloudflare MCP servers, Cloudflare MCP issue on
typefield - GitHub MCP server
- OpenCode: MCP servers
- uv: using tools (
uvxversion pinning) - OWASP MCP Top 10
- Anthropic: Code execution with MCP
- codebase-memory-mcp and preprint, Serena, Basic Memory