MCP server setup in Claude Code: add, share, debug
In short. An MCP server setup is one command, but three choices come with it: the transport (HTTP for cloud services, stdio for programs on your computer), the scope (who sees the server) and where the keys live. The default scope is local, so a server you add is invisible to your team until you use
--scope projectand a.mcp.jsonthat holds${VARIABLES}instead of secrets. This guide covers the commands, a pre-share checklist and a table of the failures behind most “my MCP tools don’t work” questions.
MCP server setup is how you let Claude Code talk to things outside your files, like a ticket tracker, a database, or your own API. MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems: data sources, tools and workflows. Adding a server takes a minute. Most trouble comes after: the server works for you but not for your team, a secret key ends up in the code, or the tools show up but never get used.
This guide follows the official MCP documentation for Claude Code, last checked on 28 October 2026. We connect MCP servers to Claude Code every day in our own studio, and the mistakes below are the ones we see most often in client setups.
What should you decide before you add an MCP server?
Three things, before you run the first command:
- Who needs it? Just you, everyone on this project, or you in every project? This is the scope, and it decides where the config is stored.
- What can it do? A server that only reads tickets is a different risk from one that can write to your database or send email. Start with read-only access when the service allows it.
- Where do the keys go? A token pasted into a shared file is the hardest mistake to fix, because it stays in the repository’s history.
How do you add an MCP server to Claude Code?
This guide covers HTTP, stdio and legacy SSE; it is not an exhaustive list of transports supported by every version. HTTP is the recommended one for cloud services:
claude mcp add --transport http notion https://mcp.notion.com/mcp
If 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"
stdio runs a program on your computer:
claude mcp add --transport stdio local-docs -- python3 /absolute/path/to/reviewed_mcp_server.py
The -- matters. Everything before it is for Claude Code; everything after it is the server’s own command, sent along unchanged. Without it, Claude Code tries to read the server’s flags as its own.
SSE is deprecated. Since version 2.1.265, Claude Code tries HTTP first and falls back to SSE on its own, so use HTTP when the service offers it.
Two smaller points. Server names added with claude mcp can contain only letters, numbers, hyphens and underscores. And a JSON entry with a url but no type is read as stdio, which is a classic reason for a server that “connects” to nothing.
What are MCP scopes, and who can see the server?
Every server has a scope, and this is where team setups usually break.
| Scope | Who it applies to | Shared with team | Stored in |
|---|---|---|---|
| local (default) | Just you, in this project | No | ~/.claude.json |
| project | Everyone in this project | Yes, through the repo | .mcp.json in the project root |
| user | You, in all your projects | No | ~/.claude.json |
Set it with --scope:
claude mcp add --transport http shared-server --scope project https://example.com/mcp
If the same server name exists in several places, local wins, then project, then user, then servers from plugins and claude.ai connectors. The winning entry is used as a whole: its fields are not merged with the others.
How do you share an MCP server with a team and keep secrets out?
The project scope creates a .mcp.json 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} becomes the variable’s value, and ${VAR:-default} uses the default when the variable is unset. This works in command, args, env, url and headers. If a variable has no value and no default, the literal text stays and claude mcp list shows a warning. So a missing key fails visibly rather than silently.
Two protections are built in, and both are good news for a shared repo:
- In an interactive session, Claude Code asks each person to approve the project’s servers before they run. A server from a repository you just cloned does not start without your say-so.
claude mcp reset-project-choicesclears those answers. - In a remote server’s
urlandheaders, variables such asANTHROPIC_API_KEYexpand to empty, so a project config cannot quietly send your Anthropic credentials to a third party. A name likeAPI_KEYexpands normally.
One thing to know: in non-interactive runs (claude -p and the Agent SDK), nobody can answer the approval prompt, so project servers load without asking. If you run Claude Code in scripts or CI, review .mcp.json as carefully as you would any code.
Checklist before you commit a .mcp.json
- No token, password or key written in any field, only
${NAME}references. - Every
${NAME}is documented in the README, with where to get the value. - Defaults only for harmless values (a base URL), never for secrets.
- Every entry has a
type; entries with aurlarehttp. - The server needs only the access the task needs: read-only first.
- You know who maintains the server, and it is one you trust.
- A teammate on a clean machine ran
claude mcp listand sawConnected. - If a key was ever pasted into the file, it is rotated, not just deleted.
How do you check that an MCP server works?
claude mcp list
claude mcp get notion
claude mcp list shows each server’s status: connected, needs authentication, failed to connect, or pending approval. In a session, /mcp shows the same and lets you sign in to remote servers with OAuth; /mcp reconnect all retries failed servers in recent versions. To remove a server, use claude mcp remove notion, which also deletes its stored OAuth tokens.
Why are the MCP tools listed but never used?
Usually the cause is one of the rows below. We use this table when we debug a client setup:
| Symptom | Likely cause | What to do |
|---|---|---|
| Works for you, not for teammates | Added with the default local scope | Re-add it with --scope project |
| A teammate sees “Pending approval” | The project server was not approved yet | Approve it in /mcp or at the start of the session |
| “Needs authentication” | The remote server wants OAuth | Run /mcp and sign in, or claude mcp login <name> |
| Failed to connect right away | url without type, a typo, or an unset variable |
Check claude mcp get, then the ${VAR} warning in claude mcp list |
Tool listed in /mcp, but Claude cannot call it |
Full name over 128 characters; Claude Code leaves such a tool out | Rename the server or tool to something shorter |
| Permission rule or hook does not match | Permission globs and hook regex matchers use different syntax | Permissions: mcp__server__*; hook matcher: mcp__server__.*. Prefer the exact tool name for a narrow rule |
| One answer fills the context | A tool returns a huge result | Claude Code warns above 10,000 tokens and caps at 25,000 by default; add filters to the tool before raising MAX_MCP_OUTPUT_TOKENS |
| Slow or hanging calls | A tool takes long or gets no progress | Startup limit is MCP_TIMEOUT; per-server timeout in milliseconds overrides the tool limit |
The tool name may be the same, but the matching syntax is not. Do not copy a hook regex into a permission rule. Inspect the actual registered name, including any plugin prefix. See the official permission reference and hook matcher reference.
Will many MCP servers fill the context window?
Much less than before. Tool search is on by default: Claude Code loads only tool names and server instructions at the start and fetches a tool’s definition when Claude needs it. The documentation says there is no fixed cap on tools per server; the practical limit is your context budget. What still costs you is the results: a tool that returns a full table every time will crowd the session, tool search or not.
When is an MCP server the wrong tool?
Not every job belongs in an MCP server:
- It is a repeatable procedure, not an outside system. A skill or a subagent fits better. Our agents versus skills guide explains the difference.
- The server is one you do not trust. Servers that fetch outside content can bring prompt injection into your session. Connect only servers you trust, and give them only the access the task needs. A hook can add a check, but it is not a security boundary on its own.
- You need a hard guarantee. MCP gives Claude capabilities; it does not limit them. Scope determines where configuration applies, not a security boundary. Access also depends on permissions and the server account’s rights.
- The task is a single read. If Claude only needs one file or one query result once, paste it in. A server is worth the setup when the connection will be used again.
When should you get help with MCP server setup?
If your team needs Claude Code connected to its own systems, with a shared config, no secrets in the repository and rules that actually fire, we set up the MCP servers, agents and tested rules and leave you a working setup. You can see how our own system works on the work page.
How to accept a connection without testing on live data
Use a test account and harmless sample data. Check four stages separately: configuration loads, authentication succeeds, one named read-only tool returns the expected sample, and a disallowed operation is refused. If no denial was tested, mark it unverified. Connected does not prove the whole workflow.
Never replace example placeholders with a real token in shared notes or screenshots. A token typed into a command can remain in shell history. Use the authentication method supported by your service; keep secrets out of Git. Review a stdio package and pin an approved version before running it.
Record version, server name, configuration scope, tested tool, expected result and actual result. Do not publish the full logs if they contain private records. This article’s examples are not an approval to install a third-party package or connect a production system.
Configuration scope determines who loads a setting, not what a server is authorised to do. Before a real connection, review the server implementation, pin approved dependencies, grant the narrowest service-account rights and test a read-only operation. Never run an unreviewed package merely because it appears in an example.
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, which use the form mcp__server__tool, and whether the full name is over 128 characters.
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.