MCP server setup in Claude Code: add, share, debug
MCP server setup is how you give Claude Code access to things outside your files: a ticket tracker, a database, a design tool, your own API. MCP (Model Context Protocol) is an open standard for these connections. The setup itself is one command, but most problems come later: the server works for you and not for your team, a key ends up in the repository, or the tools are listed and never used.
This guide follows the official MCP documentation for Claude Code. We connect MCP servers to Claude Code every day in our own studio; the mistakes listed below are the ones we see most often in client setups.
Before you add a server: three questions
- Who needs it? Only you, everyone on this project, or you in every project. The answer is the scope, and it decides where the configuration lives.
- What can it touch? A server that only reads a ticket tracker is a different risk from one that can write to your database or send email. Start read-only when the service allows it.
- Where do the keys live? Decide before the first command. A token typed into a shared file is the hardest mistake to undo, because it stays in the repository history.
Three ways to add a server
A remote server over HTTP is the usual choice for cloud services:
claude mcp add --transport http notion https://mcp.notion.com/mcpIf the service needs a token, pass it as a header:
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"A local server over stdio runs as a program on your machine:
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-serverThe -- matters. Everything before it is for Claude Code; everything after it is the server’s own command, passed unchanged.
SSE still works but is deprecated. Prefer HTTP where the service supports it.
Scopes: who sees the server
Every server is added with a scope, and this is where team setups usually go wrong.
| Scope | Where it applies | Shared with the team | Stored in |
|---|---|---|---|
| local (default) | this project, only you | no | ~/.claude.json |
| project | this project | yes, via the repository | .mcp.json in the project root |
| user | all your projects | no | ~/.claude.json |
Choose it with --scope:
claude mcp add --transport http shared-server --scope project https://example.com/mcpIf the same server name exists in several scopes, the local one wins, then project, then user. The winning entry is used as a whole; fields are not merged.
A team .mcp.json without secrets
The project scope writes a file you can commit. Keep keys out of it with environment variables:
{
"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, and ${VAR:-default} falls back to the default. If a variable has no value and no default, Claude Code warns and leaves the text as it is, so a missing key shows up as a failed connection rather than a silent one.
In an interactive session, Claude Code asks each person to approve the project’s servers before first use. That prompt is a feature: a server from a repository you just cloned should not start without your consent.
Check that the MCP server setup works
claude mcp list
claude mcp get notionclaude mcp list shows each server with a status: connected, needs authentication, or failed to connect. Inside a session, /mcp shows the same and lets you sign in to remote servers that use OAuth. To remove a server, use claude mcp remove notion.
Problems we see most often
- The server works only for you. It was added with the default local scope. Re-add it with
--scope project. - A key in the repository. Someone pasted a token into
.mcp.json. Rotate the key, then switch to${API_KEY}. - Tools listed, never allowed. Permission rules and hook matchers use full tool names:
mcp__server__tool. A matcher ofmcp__memoryalone matches nothing; see our Claude Code hooks article. - Huge answers. Claude Code warns when one tool result passes 10,000 tokens and caps it at 25,000 by default (
MAX_MCP_OUTPUT_TOKENSchanges the cap). A tool that returns a whole table every time needs filters, not a bigger limit. - A server you have not checked. Servers that fetch outside content can carry prompt injection into your session. Connect only servers you trust, and give them only the access the task needs.
If you are deciding whether a job belongs in an MCP server, a skill or a subagent, our agents vs skills guide covers the difference.
When to hand it over
If your team needs Claude Code connected to its own systems, with shared configuration, no secrets in the repository and rules that hold, we set up the MCP servers, agents and tested rules and leave you a working configuration. You can see how our own system is put together on the work page.
Questions
Why don't my teammates see the MCP server I added?
Because the default scope is local: the server is saved in your own ~/.claude.json for that project only. Add it with --scope project to write it to .mcp.json in the repository, which the team can commit.
Where do I put API keys for an MCP server?
Not in .mcp.json itself. Write ${API_KEY} in the url, headers, command, args or env fields and keep the value in an environment variable. ${VAR:-default} gives a fallback.
Why is the server listed but Claude never uses its tools?
Check claude mcp list for its status first: it may need authentication or fail to connect. Then check the tool names in your permission rules and hooks: they use the form mcp__server__tool.
Is SSE still supported?
It still works but is deprecated. Use the HTTP transport where the service offers it; recent versions try HTTP first and fall back to SSE on their own.