How to set up Claude Code MCP in 2026

• Use local scope first if you are testing whether one server solves a real workflow problem.
• Use project scope only when the repository should carry the setup through .mcp.json.
• Use user scope for personal utilities you want available across projects on your machine.
• Keep secrets in environment variables, not in .mcp.json.
• Prefer HTTP transport when the server supports it instead of old SSE examples.
• Keep the shared config small enough that reviewers can still explain why each server exists.

If you are still deciding whether Claude Code fits your workflow, read the Claude Code review first. If the real decision is Claude-first workflow versus open control, branch to Claude Code vs Cline.

Use local scope as the default safe choice

Local scope is the right default when you are testing a server, using a personal utility, or trying to keep credentials and experiments out of version control. If you are not sure, choose local first.

Use project scope when the repository should carry the setup

Project scope writes to .mcp.json in the repo root and should be treated like reviewable infrastructure. Good candidates are shared internal docs, approved company services, or repo-specific workflows every contributor should inherit.

Use user scope for personal utilities you want everywhere

User scope is private like local scope, but it follows you across projects. Use it when the tool is personal and cross-project rather than personal and repo-specific.

1. Add one server in local scope.
2. Confirm it solves a real workflow problem instead of a hypothetical one.
3. Move it to project scope only if the full team should share it.
4. Keep secrets in environment variables instead of hardcoding them into the repo.
5. Keep .mcp.json small enough that reviewers still understand it.

A low-risk first command looks like this:

claude mcp add --transport http stripe --scope local https://mcp.stripe.com

That keeps the config private to your machine, loads only in the current project, and gives you a clean way to prove the tool is useful before you ask teammates to inherit it.

When the whole repository should use the same server, switch to project scope:

claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

Claude Code then creates or updates a project-root .mcp.json file. The healthy use case is short, explainable, and reviewable. The unhealthy use case is a dumping ground for personal experiments, machine-specific paths, and credentials that should never land in version control.

Keep this file boring on purpose:

• Default to one or two shared servers, not ten.
• Require a plain-language reason for every shared server.
• Prefer HTTP transport when available.
• Test locally before you move anything into project scope.

If a shared server depends on secrets or machine-specific values, use environment variable expansion instead of hardcoding them into .mcp.json. The documented patterns are ${VAR} and ${VAR:-default}, and expansion works in command paths, args, env values, URLs, and headers.

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

Use /mcp inside Claude Code when a remote server requires OAuth. If the server needs an OAuth client secret, MCP_CLIENT_SECRET helps avoid typing it interactively. The other operational env vars worth knowing are MCP_TIMEOUT for slow startups and MAX_MCP_OUTPUT_TOKENS when responses get too large.

• Using project scope too early before a server proves its value.
• Treating .mcp.json like a secret store.
• Adding too many servers before proving the workflow.
• Forgetting that project-scoped servers trigger approvals.
• Assuming every tool belongs at the project level.
• Hardcoding machine-specific paths.
• Using deprecated SSE examples when HTTP is available.

One practical edge case from the docs: if a required environment variable is missing and there is no default value, Claude Code can fail to parse the config. When a team says the setup is broken, check env var expansion before chasing stranger theories.

Skip setup for now if you are still deciding whether Claude Code fits your workflow at all, if you only need ordinary code editing help, or if your team has not agreed on which integrations belong at repo scope.

If the real question is tool choice rather than setup, branch back into the live cluster:

When adding third-party servers, scan MCP servers before connecting them to Claude Code, then add approvals for file, shell, browser, and credential access.