2.4 Integrate MCP servers into Claude Code and agent workflows

Key points

1. 1

   Three Claude Code MCP scopes: local (default; this project only, private, stored in ~/.claude.json), project (.mcp.json at the repository root, committed and shared with the team) and user (~/.claude.json, all of one user's projects, private). Shared team tooling goes in project scope; personal or experimental servers go in user scope.

2. 2

   Add servers with claude mcp add --transport http|sse|stdio <name> --scope project|user|local ...; for stdio servers -- separates Claude's options from the server command, and --env KEY=value passes environment to the server. claude mcp list, claude mcp get <name>, claude mcp remove <name> and /mcp inside a session manage and inspect servers.

3. 3

   .mcp.json supports environment variable expansion: ${VAR} and ${VAR:-default} in command, args, env, url and headers. Reference ${GITHUB_TOKEN} in the committed file and set the variable on each machine or CI runner. Never commit token values, and do not park them in CLAUDE.md (it is committed and loaded into context).

4. 4

   If a referenced variable is unset with no default, the config still loads: claude mcp list shows a missing-variable warning and the literal ${VAR} text is used as-is, so the server may connect and then fail authentication. In CI, map the secret into the exact variable name the file expects.

5. 5

   All scopes load together. Tools from every configured server, project and user alike, are discovered at connection time and available simultaneously. If the same server name is defined in several scopes, the highest-precedence definition wins (local, then project, then user).

6. 6

   Project .mcp.json servers require a one-time approval prompt in interactive sessions; in claude -p, Agent SDK and cloud runs they load without prompting. MCP tool names appear as mcp__<server>__<tool> in permission rules, allowed-tools, subagent tools lists and hook matchers.

7. 7

   If the agent prefers a built-in tool (Grep) over a more capable MCP tool, the usual cause is a thin MCP description. Enhance it to explain capabilities, outputs and when to prefer it over the built-in alternative; do not remove the built-in tool or add blanket "always use X" prompt rules.

8. 8

   Prefer existing community or vendor MCP servers for standard integrations (Jira, GitHub, Slack, databases); reserve custom servers for team-specific workflows nothing else covers.

9. 9

   MCP resources expose content catalogues (issue summaries, documentation hierarchies, database schemas) so the agent can see what data exists without exploratory tool calls. Resources are application-driven context; tools are model-controlled actions. A static copy in CLAUDE.md or a list_everything tool are the wrong substitutes.

10. 10

    In the Agent SDK, pass servers in the mcpServers option (stdio command/args/env, or type: "http"/"sse" with url and headers); a project .mcp.json is picked up when the project setting source is enabled. Grant access with allowedTools: ["mcp__server__*"] rather than broad permission modes, and check the init system message for server status (connected, failed, needs-auth).

Read the source

• Connect Claude Code to tools via MCP
• Agent SDK — Connect to external tools with MCP
• MCP specification — Resources