MCP setup guide
Claude Code MCP: set up servers, then put them to work
Updated November 17, 20268 min read
Claude Code MCP support lets Claude use outside tools, such as GitHub, Sentry, Notion or your database, through small connector programs called MCP servers. You add one with claude mcp add, choose who it is for with a scope, and check it with /mcp inside a session. This page explains MCP in plain words, gives the exact setup commands, shows real example servers, and covers what to do when one will not connect.
MCP in plain words: a travel adapter for AI tools
Think of a travel adapter. Your laptop charger does not need to know the shape of every wall socket in the world. The adapter handles that, so one plug works everywhere. MCP (Model Context Protocol) is that adapter for AI apps. A service like GitHub builds one MCP server, and any app that speaks MCP, including Claude Code, can plug into it.
Out of the box, Claude Code can read and edit files and run commands in your terminal. Each MCP server you add gives it new tools: read your GitHub issues, look up an error in Sentry, query a database, update a Notion page. Claude decides when a tool is useful, and every tool call still goes through your normal permission settings.
Servers come in two kinds. A remote server lives on the internet and Claude Code talks to it over HTTP, often with a sign-in. A local server is a small program that runs on your own computer, started by a command, and talks to Claude Code over stdio (its standard input and output).
Before adding a server, check whether a command-line tool already does the job. Anthropic notes that tools like gh, aws, gcloud and sentry-cli are more context-efficient than MCP servers, because Claude can run them directly.
Add an MCP server to Claude Code in five steps
- 1
Find the server's address or command
Remote servers publish a URL, such as
https://mcp.notion.com/mcp. Local servers publish a start command, often beginning withnpx. - 2
Pick a scope
Local (default) is just you in this project. Project shares it with your team through a
.mcp.jsonfile. User makes it available in all your projects. - 3
Run claude mcp add
In your terminal, run
claude mcp add --transport http notion https://mcp.notion.com/mcp, swapping in your server's name and URL. - 4
Sign in if asked
Start
claude, type/mcp, choose the server and follow the browser sign-in. Claude Code stores the token and refreshes it for you. - 5
Check it works
Run
claude mcp listto see every server and its health, then ask Claude something that needs the new tool.
The claude mcp add command, piece by piece
Remote server over HTTP (recommended)
claude mcp add --transport http <name> <url>
# with a sign-in header
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"Local server over stdio
claude mcp add [options] <name> -- <command> [args...]
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-serverFrom a JSON snippet
claude mcp add-json <name> '<json>'- Put Claude Code's own options (
--transport,--env,--scope,--header) before the server name. - For local servers, the
--separates Claude Code's options from the server's command. Everything after it goes to the server untouched. - Short forms exist:
-tfor transport,-Hfor header,-efor env,-sfor scope. - Server names may only use letters, numbers, hyphens and underscores.
- SSE servers still work with
--transport sse, but Anthropic marks SSE as deprecated. Use HTTP when a server offers it.
Claude Code MCP config scopes
| Scope | Who gets it | Shared through git? | Stored in |
|---|---|---|---|
local (default) | You, in this project only | No | ~/.claude.json, under this project |
project | Everyone working on this project | Yes | .mcp.json in the project root |
user | You, in every project | No | ~/.claude.json |
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/anthropicIf the same server name exists in more than one place, local wins over project, project over user, and user over servers from plugins and claude.ai connectors. Claude Code uses the winning entry as a whole; it does not merge fields between scopes.
What a .mcp.json file looks like
Project-scoped servers live in a .mcp.json file at the root of your project. You can write it by hand. It supports environment variables, so keys stay out of the file you commit:
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}${VAR}is replaced with the variable's value. It works incommand,args,env,urlandheaders.${VAR:-default}uses the default only when the variable is not set at all.- If a variable is missing and has no default, the server still loads with the literal text, and
claude mcp listshows a warning. - The first time someone opens the project, Claude Code asks them to approve its
.mcp.jsonservers.claude mcp reset-project-choiceslets you answer again.
Example MCP servers for Claude Code
There is no official ranking of the best MCP servers for Claude Code, and the right ones depend on the tools you already use. These are servers that Anthropic's own MCP docs use as examples, which makes them a safe place to start:
GitHub
Read issues and pull requests. Remote, at https://api.githubcopilot.com/mcp/, signed in with a personal access token header.
Sentry
Look up production errors and their stack traces. Remote, at https://mcp.sentry.dev/mcp, signed in through /mcp.
Notion
Read and update pages and databases. Remote, at https://mcp.notion.com/mcp.
PostgreSQL via DBHub
Ask questions of a database. Local, run with npx -y @bytebase/dbhub. Use a read-only database user.
Airtable
Work with bases and records. Local, run with npx -y airtable-mcp-server and your API key in --env.
Asana
Tasks and projects. Uses the older SSE transport at https://mcp.asana.com/sse.
HubSpot
CRM records. Remote, at https://mcp.hubspot.com/anthropic, often added at user scope.
Your claude.ai connectors
Connectors you added on claude.ai show up in Claude Code automatically when you sign in with that account.
# GitHub
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"
# Sentry (then run /mcp to sign in)
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
# Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp
# PostgreSQL via DBHub (read-only user)
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"
# Asana (SSE)
claude mcp add --transport sse asana https://mcp.asana.com/sseWatch out
An MCP server can do whatever its tools allow with the access you give it. Install servers only from sources you trust, give database servers a read-only login, and never paste real keys into a .mcp.json you commit. Our vibe coding security guide covers keys in more depth.
Two more tricks. On macOS or WSL, claude mcp add-from-claude-desktop imports servers you already set up in the Claude Desktop app. And claude mcp serve turns Claude Code itself into an MCP server that other apps can connect to.
Managing your MCP servers day to day
| Command | What it does |
|---|---|
claude mcp list | Every server with its health status |
claude mcp get <name> | The saved URL or command, scope and settings for one server |
claude mcp remove <name> | Delete a server and its stored sign-in |
claude mcp login <name> | Sign in to a server from the terminal |
claude mcp logout <name> | Clear a server's stored sign-in |
/mcp | Inside a session: status, sign-in, reconnect, enable or disable |
/mcp reconnect all | Retry every failed or signed-out server |
MCP servers can also offer prompts, which appear as commands like /mcp__github__list_prs, and resources you can mention with @, the same way you mention a file.
Troubleshooting Claude Code MCP servers
The server shows as failed in /mcp
Run claude mcp get <name> and check the URL or command for typos. For a local server, run its start command yourself in a terminal: a missing package or a wrong key shows up straight away. Fix it, then use /mcp reconnect <name>.
It keeps asking you to sign in
Claude Code notices a server needs sign-in when it answers with a 401 or 403 error. Open /mcp, pick the server and finish the browser step. If you are on a machine without a browser, claude mcp login <name> prints a link to open elsewhere.
Your flags went to the wrong program
For local servers, anything you want the server to receive must come after --. Without it, Claude Code tries to read flags like --port as its own. Also put --transport stdio between --env and the server name, or the name gets read as another variable.
A project server never loads
Servers from .mcp.json need your approval the first time. If you declined by accident, run claude mcp reset-project-choices and open the project again.
The server is slow to start
Raise the startup timeout for one run with MCP_TIMEOUT=10000 claude, which allows 10 seconds. A single server's tool timeout can be set with a timeout value in its .mcp.json entry.
Tool output is cut off
Claude Code warns when one tool result passes 10,000 tokens and limits output to 25,000 tokens by default. Start with MAX_MCP_OUTPUT_TOKENS=50000 claude to raise the limit, or ask for smaller results.
A tool appears in /mcp but Claude never uses it
Select the tool in /mcp to see its full name. Claude Code leaves out any MCP tool whose full name is longer than 128 characters, because the API would reject it. A shorter server name usually fixes it.
Do MCP servers eat into your usage limits?
Less than they used to. As of November 2026, tool search is on by default: only tool names and server instructions load when a session starts, and the full tool details load only when Claude needs them. Adding servers therefore has a small effect on your context window. Tool results still count, though. Run /context to see what is using space, check /usage for each server's share of your plan, and switch off servers you are not using in /mcp. Our Claude Code pricing guide has more ways to save.
MCP-connected agents in a VibeCodingDeck grid
VibeCodingDeck does not replace or copy your MCP setup. Each pane runs your own Claude Code, so every server you added with claude mcp add, at any scope, is there in every session. What it adds is the room around your agents: up to 12 sessions in one grid on Windows 10/11 or Apple-silicon Macs, alerts when one needs you, a live usage meter, and per-project boards and notes. It can also send your users' Sentry crash reports and GitHub issues straight to an agent. See the Claude Code GUI page and features, or learn the CLI basics first in how to use Claude Code.
MCP questions from Claude Code users
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> for a local one. Then open /mcp in a session to sign in and check that it connected.
Where is the Claude Code MCP config stored?
+
Local and user scope servers are stored in ~/.claude.json. Project scope servers are stored in .mcp.json at the project root, so they can be committed and shared.
How do I share MCP servers with my team?
+
Add them with --scope project. That writes .mcp.json, which you commit. Each teammate approves the servers the first time they open the project.
What does the -- mean in claude mcp add?
+
It separates Claude Code's own options from the command that starts a local server. Everything after -- is passed to the server exactly as written.
How do I remove an MCP server from Claude Code?
+
Run claude mcp remove <name>. That deletes the config and its stored sign-in. Run claude mcp list afterwards to confirm it is gone.
Sources
Run up to 12 AI coding agents in one window.
Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.
Get startedKeep reading
Hooks cookbook
Claude Code hooks cookbook: 8 recipes to paste into settings.json
Hands-on Claude Code guide
Claude Code subagents: build a custom agent step by step
Beginner lesson plan
How to use Claude Code: a six-lesson course for beginners
Buyer's map
Claude Code GUI: a buyer's map of every visual way to run Claude Code