Integrating MCP servers

Choose the right MCP scope

An MCP server is a separate process exposing tools to Claude over the Model Context Protocol (MCP), an open standard for connecting assistants to external systems. Where you register one decides who else gets it.

Standard is the operative word. Any MCP-capable client speaks the same protocol, so one server implementation serves all of them and the integration is written and maintained once rather than once per application. What the protocol standardizes is the interface, not the hosting, the speed, or who is permitted to call it.

• Local scope — private to you and limited to the current project. This is the default and is stored under that project's path in ~/.claude.json.
• Project scope — shared team tooling in .mcp.json, which travels in version control.
• User scope — private tooling available across all your projects, stored in ~/.claude.json.

Where each one is stored, which is what decides who else gets the server:

local     ~/.claude.json, under this project's path   you, this project
user      ~/.claude.json                              you, every project
project   .mcp.json                                   everyone who clones

Two of the three are the same file. Nothing in a filename tells you which scope you picked, so pick it on purpose rather than by accepting the default.

This follows the same scoping principle as CLAUDE.md and slash commands: choosing the wrong level changes who can use the configuration.

Credentials

.mcp.json supports environment variable expansion, so configuration references ${GITHUB_TOKEN} and the value lives in the environment. The file is committable; the secret is not in it.

Servers live under an mcpServers key, each with the command that starts it:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@example/github-mcp"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

The token appears here as the literal text ${GITHUB_TOKEN}. The value lives in the environment, so this file is safe to commit and the secret never enters version control.

A private repository doesn't make committed secrets safe. Repositories are cloned onto laptops, copied into backups, and shared with new collaborators. Git history can also preserve a secret long after the visible line is deleted.

Tool Search reduces initial context use

Current Claude Code enables MCP Tool Search by default on supported models. Only tool names and server instructions load initially; full tool schemas are deferred until Claude needs them. This makes adding servers much cheaper in context than loading every definition up front, but descriptions still matter: Claude needs enough signal to know which deferred tool to retrieve.

Tool Search works only when tool names and descriptions are clear enough for Claude to identify the right definition to load.

Tool Search has platform and configuration fallbacks that load definitions upfront, so a sprawling or overlapping tool catalog is still a design concern.

Make MCP tools easy to identify

An agent may use a familiar built-in tool such as Grep instead of a more capable MCP tool when the MCP tool's purpose is unclear.

The fix is a description problem, not a configuration one: explain the MCP tool's capabilities and outputs in enough detail that it is visibly the better choice for the job.

Use existing servers where they exist

For standard integrations — an issue tracker or a source host — prefer a maintained community server. Reserve custom servers for workflows that are specific to the team and are not supported by an existing server.

Resources reduce unnecessary exploration

MCP resources expose content catalogs: issue summaries, documentation hierarchies, database schemas. Given a catalog, the agent can see what exists instead of making exploratory tool calls to discover it. That is fewer calls, less latency, and fewer tokens spent finding out what is available.