Claude Code MCP Setup: How to Add MCP Servers (2026 Guide)

I keep seeing the same pattern. Developers hear about MCP, read one paragraph that calls it "the USB-C port for AI," nod along, and then have no idea what to actually do with that information.

Which is a problem because the Model Context Protocol is not some theoretical standard that might matter someday. It has over 97 million monthly SDK downloads. Anthropic, OpenAI, Google, Microsoft, and Amazon have all adopted it. The Linux Foundation created an entire foundation around it. And the developers who understand it are building AI workflows that make everyone else's look like toys.

So let me do what most MCP articles fail to do. This guide starts with the exact commands to add MCP servers to Claude Code, then explains how the protocol works, which servers are worth installing, and what can go wrong. If you want the higher-level framing first, read what an MCP server is.

How Do You Add an MCP Server to Claude Code?

Run claude mcp add with a name and either a URL (for a remote server) or a command (for a local one). Claude Code stores the server in one of three scopes: local, project, or user. Run /mcp inside a session to check status and authenticate. Project-scoped servers live in .mcp.json, which you can commit and share with your team.

Claude Code MCP Commands: claude mcp add

Here is the current form, checked against the Claude Code docs.

Remote server over HTTP (the recommended transport for hosted servers):

claude mcp add --transport http notion https://mcp.notion.com/mcp

Remote server with an auth header:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Local server over stdio. Everything after -- is the command that launches the server:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Three details that trip people up:

• The -- separator matters. Everything before it is parsed as Claude Code options. Everything after it goes to the server unchanged. Without it, a server flag like --port gets read as a Claude Code flag.
• --env accepts multiple KEY=value pairs. If the server name comes directly after --env, the CLI reads it as another pair and rejects it, so put another option such as --transport stdio between them.
• The older SSE transport (--transport sse) is deprecated. Use HTTP unless a server only offers SSE.

You can also add a server from a JSON blob, which is handy when a vendor gives you a config snippet:

claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp"}'

Always include "type". An entry with a url but no type is read as a stdio server and fails.

Manage and check your servers

claude mcp list
claude mcp get notion
claude mcp remove notion

claude mcp list shows each server's health. Inside a Claude Code session, /mcp shows status, lets you authenticate OAuth servers, reconnect, and toggle servers off without removing them.

Claude Code MCP Scopes: Local, Project, and User

Every server you add has a scope, set with --scope (or -s). The default is local.

claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

If the same server name exists in more than one scope, local wins over project, and project wins over user. Claude Code uses the whole entry from the winning scope and does not merge fields.

My rule of thumb: personal tools and anything with a personal token go in user or local scope. Servers the whole team needs (your issue tracker, your docs) go in project scope so a new teammate gets them on git clone.

The .mcp.json file

Project scope writes a .mcp.json file at the repo root. You can edit it by hand:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

.mcp.json supports environment variable expansion: ${VAR} and ${VAR:-default} work in command, args, env, url, and headers. That is how you commit the file without committing secrets. If a variable is unset and has no default, the server still loads with the literal ${VAR} text and Claude Code shows a warning.

For safety, Claude Code asks you to approve project-scoped servers from .mcp.json before it uses them in an interactive session. To reset those choices, run claude mcp reset-project-choices.

What MCP Actually Is (Without the Buzzwords)

Here is the core problem MCP solves.

You have an AI model. It is smart. It can reason, write code, analyze data. But it lives in a box. It cannot read your files, query your database, check your GitHub issues, or send a Slack message. Not without you copy-pasting context into the chat window like it is 2023.

Before MCP, every tool that wanted to connect an AI model to external services had to build custom integrations. Claude needed its own GitHub connector. ChatGPT needed its own. Cursor needed its own. Every AI app times every external service equals an absurd number of one-off integrations. The classic N times M problem.

MCP standardizes that connection. You build one MCP server for GitHub, and it works with Claude, ChatGPT, Cursor, VS Code Copilot, and any other AI tool that speaks MCP. One server, every client. This is what makes context engineering a practical skill rather than a vague buzzword. It is also the data layer that sits underneath the new Claude Code plugin marketplace, where MCP servers ship as plugin components alongside skills and hooks.

The architecture is borrowed from something most developers already know: the Language Server Protocol. LSP standardized how editors talk to language tools. You build one TypeScript language server and it works in VS Code, Neovim, Sublime, and everywhere else. MCP does the same thing but for AI-to-tool communication.

The Architecture in Plain English

MCP uses a client-server model with JSON-RPC 2.0 as the message format. There are three roles.

The host is the application you interact with. Claude Desktop, Cursor, VS Code, your custom AI app. The host creates and manages MCP clients.

The client lives inside the host. Each client maintains a one-to-one connection with a specific MCP server. It handles the handshake, protocol negotiation, and message routing. If your host connects to three MCP servers (GitHub, Slack, PostgreSQL), it runs three separate clients.

The server is the bridge between the AI and the external world. It exposes capabilities that the AI can discover and use. This is what you build or install when you want the AI to interact with a new service.

What Servers Expose: Three Primitives

Every MCP server can expose three types of capabilities.

Tools are executable actions. Think of them as functions the AI can call. create_github_issue, query_database, send_slack_message. The AI model decides when to call them based on your conversation. Each tool has a defined input schema and output format.

Resources are read-only data. Files, database schemas, configuration documents, log entries. The AI can fetch and read them but cannot modify them through this primitive. Resources give the model context without giving it a write operation.

Prompts are reusable templates. Pre-built instructions that help structure how the AI interacts with specific tools. Think of them as expert-crafted starting points for common workflows.

The distinction matters. Tools are actions (the model calls them). Resources are data (the application fetches them). Prompts are templates (the user selects them).

How Messages Travel: Transport Layer

MCP supports two transport methods.

stdio is for local integrations. The client launches the MCP server as a subprocess on your machine and communicates through standard input and output. This is what happens when you run a local MCP server in Claude Code or Cursor. Fast, simple, no network overhead.

Streamable HTTP is for remote integrations. The MCP server runs as a web service and the client connects over HTTP. This replaced the older SSE (Server-Sent Events) transport that was deprecated in mid-2025. Streamable HTTP is what enables cloud-hosted MCP servers that teams share.

For most individual developers, stdio is what you will use day to day. Streamable HTTP matters more when you are building production systems or your organization hosts shared MCP servers, especially if you lean toward local-first software.

Why This Matters Right Now

I want to explain why the timing is significant because MCP did not become important gradually. It reached a tipping point.

Anthropic open-sourced MCP in November 2024. Within 48 hours, the spec repo had thousands of GitHub stars and developers started building community servers. By early 2025, OpenAI had adopted it for their Agents SDK and ChatGPT desktop app. Google followed with Gemini support. Microsoft integrated it into Copilot and VS Code natively.

Then in December 2025, something bigger happened. Anthropic donated MCP to the newly created Agentic AI Foundation under the Linux Foundation. The co-founders were Anthropic, Block, and OpenAI. The platinum members include Amazon Web Services, Bloomberg, Cloudflare, Google, and Microsoft.

That is not just adoption. That is every major AI company agreeing on a shared standard and putting it under neutral governance. It is the kind of industry alignment that usually takes years and happens in months here.

The same foundation now governs A2A, the agent-to-agent protocol that handles the part of the stack MCP deliberately does not cover. If you are building anything where independent agents need to coordinate, the A2A vs MCP breakdown is the companion read for this guide.

The foundation also houses two other projects worth knowing about. Goose is Block's open-source AI agent framework built on MCP. And AGENTS.md is OpenAI's standard for giving AI coding agents project-specific guidance (similar to CLAUDE.md if you use Claude Code).

The practical consequence: if you build an MCP server today, it works with essentially every major AI tool on the market. That was not true a year ago. It is true now. If you want the hands-on version of that build, the first MCP server walkthrough covers the stdio setup, the tool-design rules I wish I had known earlier, and the wiring into Claude Code.

Cursor and VS Code MCP Config

The same MCP server works across Claude Code, Cursor, and VS Code. You configure it once per client. The config file format differs but the server is identical.

Cursor

Cursor uses a JSON file (.cursor/mcp.json in a project) with an mcpServers key. Local servers take a command and args. Remote servers take a url.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "my-remote-server": {
      "url": "https://my-mcp-server.example.com/mcp"
    }
  }
}

VS Code

VS Code reads .vscode/mcp.json, which is nice because you can commit it to your repo and share the setup with your team. The top-level key is servers, and each entry has a type.

{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Best Claude Code MCP Servers to Install

There are thousands of MCP servers. The official MCP registry at registry.modelcontextprotocol.io is the place to browse them. These are the ones I would start with, each checked against the vendor's own docs. Remote servers authenticate with OAuth through /mcp or a token header.

Notes on the list:

• GitHub is the one I use most, for triaging issues and drafting PR descriptions. Use the remote server from GitHub. The old @modelcontextprotocol/server-github package was moved to the archived servers repo, so older tutorials (including an earlier version of this one) point at a dead end.
• Brave Search moved the same way. The original reference server is archived and replaced by Brave's own @brave/brave-search-mcp-server.
• Postgres: the original reference Postgres server is archived too. DBHub is the example the Claude Code docs use. Give it a read-only user.
• The MCP project says its own reference servers are educational examples, not production-ready. Read the code before pointing them at anything sensitive.

Each server you connect adds tool definitions to your context. Keep the list short. Five servers you use beat twenty you installed once.

The Three-Layer Protocol Stack

This is the part most articles skip, and it is where things get genuinely interesting for the future of AI development.

MCP is one layer in what is becoming a three-layer architecture for agentic AI.

Layer 1: MCP (Agent to Tool). This is what we have been discussing. A single AI agent connects to tools and data sources through MCP servers. It handles resource access, tool execution, and context delivery.

Layer 2: A2A, Agent to Agent. This is Google's protocol, launched in April 2025, that handles communication between multiple AI agents. If MCP is how an agent talks to tools, A2A is how agents talk to each other. An orchestrator agent can delegate a research task to a specialized research agent, which can delegate a data query to an analytics agent. Each agent maintains its own MCP connections but coordinates with peers through A2A.

A2A uses a discovery mechanism called Agent Cards, hosted at /.well-known/agent.json, so agents can find and understand each other's capabilities automatically.

Layer 3: WebMCP (Agent to Web). This is an emerging proposed standard that lets websites declare their capabilities as structured tools that AI agents can call directly in the browser. Instead of an agent scraping a travel site's UI to book a flight, the site publishes an MCP-compatible interface that the agent calls programmatically. Chrome 146 Canary shipped with built-in WebMCP support in February 2026.

The analogy to TCP/IP is deliberate. Each layer has clear responsibilities, can evolve independently, and protocols at each layer can be swapped without breaking the others. The flow goes: user intent captured at the UI layer, A2A delegates between agents, MCP executes tool calls, and responses render back up through the stack.

We are still early in this stack. A2A reached v1.0 in March 2026 and WebMCP is in preview. For the A2A side in depth, see A2A vs MCP. But the architectural direction is clear, and understanding it now gives you a significant advantage in building AI-powered systems that will age well.

MCP Security: The Part Nobody Wants to Talk About

I need to be direct about this because most MCP articles hand-wave over security with a sentence about "following best practices." The reality is more concerning.

Research has found that 43% of MCP servers contain command injection vulnerabilities that could enable remote code execution. About 5% of open-source MCP servers have been seeded with tool poisoning attacks where manipulated tool descriptions trick the AI into unsafe actions. And roughly 22% of servers allow file system access outside their intended boundaries.

Here are the specific attack categories you need to understand.

Tool poisoning is when an attacker crafts a malicious MCP server (or compromises an existing one) with tool descriptions designed to manipulate the AI's behavior. The tool looks legitimate but its metadata contains instructions that redirect the AI's actions.

Supply chain attacks target the MCP server distribution chain. The most notable example was the 2025 Postmark MCP breach where hackers backdoored an npm package so that compromised MCP servers would BCC every outgoing email to the attackers. This is real, not theoretical.

Rug pull attacks are when a server changes its behavior after initial trust is established. The tool definitions shift between calls, and actions you approved earlier now do something different.

The CVE to know about: CVE-2025-6514 was a critical command injection bug in mcp-remote where malicious servers could send crafted authorization endpoints that achieved remote code execution on the client machine.

What to Do About It

The MCP spec has evolved its security model significantly. OAuth 2.1 with mandatory PKCE was added in March 2025. The June 2025 update formally separated MCP servers from authorization servers and required Protected Resource Metadata (RFC 9728).

But spec-level security only helps if you practice it.

Audit before you install. Check the source code, star count, maintenance history, and author reputation of any community MCP server. The same caution you apply to npm packages applies here, arguably more because MCP servers have access to your AI agent's execution context.

Enforce least privilege. Give each MCP server access to only what it needs. The filesystem server should only see the directories you specify. The database server should use a read-only connection unless writes are genuinely needed.

Use human-in-the-loop for sensitive operations. Tools that can send emails, create issues, modify files, or execute code should require your approval before the AI acts. Most MCP clients support approval workflows. Use them.

Watch for unexpected behavior. If an MCP server starts suggesting actions you did not ask about, asking for permissions it should not need, or behaving differently than it did before, disconnect it and investigate.

The security landscape for MCP is improving fast, but right now it resembles the early npm ecosystem. Useful, powerful, and requiring a healthy dose of skepticism about what you install.

Building Your Own MCP Server

If you want to expose your own tools or services to Claude Code, building an MCP server is straightforward. The official SDK handles the protocol, and you register tools. I wrote a full walkthrough with a complete working example, tool design rules, testing, and deployment: how to build an MCP server in TypeScript.

Once it runs, you add it to Claude Code like any other stdio server with claude mcp add my-server -- npx tsx src/index.ts.

SDKs are available in TypeScript, Python, Java, Kotlin, C#, Go, Rust, Ruby, PHP, and Swift. The TypeScript and Python SDKs are the most mature and best documented.

Where This Is Going

The MCP specification is versioned by date. The latest revision is 2026-07-28. It makes the protocol stateless (no initialize handshake, no protocol-level sessions), moves experimental tasks into an official extension, and deprecates the old HTTP+SSE transport along with the Roots, Sampling, and Logging features. For you as a Claude Code user, nothing changes in the commands above. For people hosting servers, it makes remote servers simpler to scale.

Gartner predicts that 40% of enterprise applications will include task-specific AI agents by end of 2026, up from under 5% in 2025. MCP is the connective tissue that makes those agents useful. An AI agent without tool access is a chatbot. An AI agent with MCP connections to your actual infrastructure is a teammate.

The developers who understand this protocol now will have a significant head start. Not because MCP is hard to learn (it is not), but because the architectural patterns you build around it compound over time. The MCP servers you set up, the workflows you design, and the custom integrations you create all make the AI more capable in your specific environment.

If you have been using AI tools by pasting context into chat windows, MCP is the upgrade that changes everything about that workflow. Set up a couple of servers, see the difference, and you will not go back.

Getting Started Today

If you want to try MCP right now, here is the path of least resistance.

1. Pick one tool you already use (Claude Code, Cursor, or VS Code)
2. Add the GitHub MCP server with a personal access token
3. Start a conversation and ask the AI to look at your recent issues or PRs
4. Notice how different the experience feels when the AI has direct access versus when you paste a link

That is the moment it clicks. Not reading about MCP, but feeling the difference between an AI that can see your tools and one that cannot.

From there, add servers for the services you use most. Database, Slack, filesystem, whatever fits your workflow. Each one makes the AI more capable and your conversations more productive. If you are a founder shipping in public, a marketing-shaped MCP that drafts social posts from the same agent session you are coding in is worth trying. I built one on makers.page, but that project is now paused.

Frequently Asked

What is claude mcp? claude mcp is the Claude Code CLI command group for managing MCP servers: claude mcp add, list, get, and remove. It connects Claude Code to external tools and data through the Model Context Protocol.

How do I add an MCP server to Claude Code? Run claude mcp add --transport http <name> <url> for a remote server, or claude mcp add <name> -- <command> [args] for a local one. Then run /mcp in a session to check it connected and to authenticate if it uses OAuth.

Where does Claude Code store MCP servers? Local and user scope are stored in ~/.claude.json. Project scope is stored in a .mcp.json file in the project root, which you can commit.

What is the difference between local, project, and user scope? Local (the default) applies to the current project and is private to you. Project is shared with your team through .mcp.json. User applies to all your projects and is private to you.

How do I remove an MCP server from Claude Code? Run claude mcp remove <name>. To turn one off temporarily, use /mcp inside a session.

How do I keep secrets out of .mcp.json? Use ${VAR} expansion in url, headers, env, command, and args, and set the variable in your shell.

Can I build my own MCP server for Claude Code? Yes. See how to build an MCP server in TypeScript, then register it with claude mcp add.

The MCP specification is the authoritative reference. The MCP server registry has the official and community servers. And the SDKs have solid getting-started guides for building your own.