lockstep
5 min readNaman Jain

Claude Code MCP setup: config file, scopes, and .mcp.json

How to add MCP servers to Claude Code: claude mcp add, local vs project vs user scope, where the config lives, .mcp.json for teams, and common fixes.

The Playwright server works in one project and vanishes in the next. A teammate clones the repo and none of your MCP servers are there. The GitHub token ended up committed in a JSON file. All three come from the same thing: not knowing where Claude Code keeps MCP configuration.

This guide covers adding servers, the three scopes, the config files, team sharing, and common fixes, from Anthropic's MCP documentation, checked on 16 November 2026.

Adding a server

There are two kinds of server, and each has one command shape.

Remote server (a URL). Use --transport http:

claude mcp add --transport http linear https://mcp.linear.app/mcp

If the setup instructions give an API key header, pass it with --header. If the server uses OAuth, run /mcp inside a Claude Code session to sign in.

Local server (a launch command). Put the whole command after --, so flags like -y go to the server, not to Claude Code:

claude mcp add playwright -- npx @playwright/mcp@latest

From a JSON block. If a server's instructions only give JSON for another client, use add-json:

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer ${GITHUB_PAT}"}}'

A JSON entry with a url but no type is an error: Claude Code treats an entry without a type as a local stdio server, so add "type": "http".

The three scopes

The scope decides which projects a server loads in, and whether the team gets it.

ScopeLoads inShared with teamStored in
Local (default)The current project onlyNo~/.claude.json, under that project's path
ProjectThe current project onlyYes, through version control.mcp.json in the project root
UserAll your projectsNo~/.claude.json

Choose with --scope:

claude mcp add --transport http sentry --scope project https://mcp.sentry.dev/mcp
claude mcp add --transport http stripe --scope user https://mcp.stripe.com

Use local for experiments and anything with personal credentials, project for servers the whole team needs, and user for tools you want everywhere. Note that MCP's "local" scope lives in ~/.claude.json in your home directory, not in .claude/settings.local.json; the documentation calls out that the two are different.

If a server is defined twice, Claude Code connects once, using the highest-precedence definition: local, then project, then user, then plugin-provided servers, then claude.ai connectors. Fields are not merged across scopes.

Sharing servers with your team: .mcp.json

A project-scoped server is written to .mcp.json in the project root. Commit it, and every teammate gets the same servers:

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

Two things make this safe to commit:

  • Environment variable expansion. ${VAR} expands to the variable's value, and ${VAR:-default} uses a default when it isn't set. It works in command, args, env, url, and headers. Keep secrets in each person's environment, not in the file.
  • Approval. A teammate who opens the project sees new .mcp.json servers as pending until they approve them in an interactive Claude Code session. A server someone rejected is listed as rejected.

Managing servers

claude mcp list          # every server, with a health status
claude mcp get sentry    # details for one server
claude mcp remove sentry # remove it

Inside a session, /mcp shows server status and handles OAuth sign-in. claude mcp list reports statuses such as connected, needs authentication, failed to connect, and pending approval for .mcp.json servers you haven't approved yet. Removing a remote server also deletes the OAuth tokens Claude Code stored for it.

How many servers is too many?

Less of a problem than it used to be. Claude Code uses tool search: only tool names and server instructions load at session start, and full tool definitions load when Claude needs them. The documentation says this means adding more servers has minimal impact on your context window, and there is no fixed per-server tool cap.

The remaining reason to stay selective is trust. Every server is another system the agent can read from or act on. Connect the servers your work needs, with the narrowest access each one offers, such as Linear's read-only endpoint. More in MCP security: risks and best practices. For which servers are worth it, see the best MCP servers for product engineers and dev teams.

Common fixes

ProblemFix
Server works in one project, missing in anotherIt was added at local scope. Re-add with --scope user
Teammates don't have the serverAdd with --scope project and commit .mcp.json
Server shows "pending approval"Run claude interactively in the project and approve it
"has a url but no type" errorAdd "type": "http" to the JSON entry
Flags like -y are rejectedPut the launch command after --
A tool call runs too longSet a per-server timeout in milliseconds, or MCP_TOOL_TIMEOUT
Large tool results get cutRaise MAX_MCP_OUTPUT_TOKENS

Where Lockstep fits

Lockstep's MCP server gives Claude Code the team's approved decisions: the get_product_context tool returns the decisions that apply to the work. You don't need to add it by hand. npx lockstep-cli onboard configures the server and a session-start hook for the project, and asks you to approve the MCP server when Claude Code opens. Decisions come from PRDs, Slack, and pull requests and become binding when their owner approves them.

Session briefings work with Claude Code today; any MCP client can call the tools. See how it works.

Sources checked 16 November 2026

For what MCP servers are, see MCP server. For the other settings files, see Claude Code settings.json. For memory servers, see the best MCP memory server for Claude Code. For how MCP fits with skills and hooks, see CLAUDE.md vs skills vs hooks vs subagents. For how MCP relates to A2A and ACP, see MCP vs A2A vs ACP. For why MCP rather than calling APIs directly, see MCP vs API. To write your own server, see how to build an MCP server.

Frequently asked questions

How do I add an MCP server to Claude Code?
For a remote server, run claude mcp add --transport http <name> <url>, then /mcp in a session to sign in if it uses OAuth. For a local server, put its launch command after a double dash, for example claude mcp add playwright -- npx @playwright/mcp@latest.
Where is the Claude Code MCP config file?
It depends on the scope. Local and user scoped servers are stored in ~/.claude.json in your home directory. Project scoped servers are stored in .mcp.json in the project root, which you commit so the team shares them.
What is the difference between local, project, and user scope?
Local, the default, loads in the current project only and stays private. Project loads in the current project and is shared through .mcp.json in version control. User loads in all your projects and stays private. Choose with --scope local, project, or user.
How do I share MCP servers with my team?
Add them with --scope project. Claude Code writes them to .mcp.json in the project root; commit the file. Teammates approve the servers the first time they run Claude Code in the project. Use ${VAR} expansion for API keys so no secret is committed.
How many MCP servers can Claude Code use?
There is no fixed per-server tool cap. Claude Code uses tool search, which loads only tool names and server instructions at session start and fetches full tool definitions when needed, so more servers have little impact on the context window.

Keep reading