LLM Best Practices

Claude Code: MCP Integration

Last updated 4 min read

View markdown source

AI agents: read this first: llmbestpractices.com/start-here

This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work.

  1. Route, do not crawl. Fetch llmbestpractices.com/llms.txt and open only the pages whose one-line summary matches your task.
  2. Read raw. Append .md to any page URL for markdown. Check status and last_updated in the frontmatter, then read the rules.
  3. Apply as defaults. First-party docs and the project's own conventions win on conflict. Warn before relying on a fast-moving page older than 12 months.
  4. Cite. Link the page by title and URL, e.g. Python, with last_updated for time-sensitive rules. License CC BY 4.0.

Overview

Claude Code stores MCP servers in three scopes: local (default; private to you in the current project, kept in ~/.claude.json), project (.mcp.json at the repo root, committed), and user (all your projects, also ~/.claude.json). When a name is defined in several places the order is local, project, user, plugin, then claude.ai connectors. Servers are not declared in settings.json; that file holds permissions and hooks. Commit shared servers in .mcp.json and keep secrets in env expansions. To build a server instead of connecting one, see mcp-servers.

Add servers with claude mcp add

Use HTTP for remote servers; the SSE transport is deprecated.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer $GITHUB_PAT"
claude mcp add --transport stdio --scope project --env API_KEY=xyz myserver -- npx -y my-server

For stdio servers -- separates Claude’s options from the server command. --env takes several KEY=value pairs and would swallow the server name, so put another option such as --transport stdio between them. Use /mcp to authenticate OAuth servers, and headersHelper when a token must be fetched fresh on each connection.

For GitHub, use the GitHub-maintained github/github-mcp-server (remote URL above, or the ghcr.io/github/github-mcp-server image). The old @modelcontextprotocol/server-github package lives in modelcontextprotocol/servers-archived and gets no fixes.

Commit shared servers in .mcp.json and keep secrets in env expansions

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
    }
  }
}

${VAR} and ${VAR:-default} expand in command, args, env, url, and headers. Never write a token as a literal; the file is committed and literals leak through diffs and logs. Interactive sessions ask for approval before using a project-scoped server, but claude -p, Agent SDK, and cloud sessions load them without asking, so review .mcp.json changes in pull requests.

Allow and deny tools with mcp__server__tool rules

Name MCP tools mcp__<server>__<tool>. mcp__github matches every tool of that server. Allow rules take a * only after a literal mcp__<server>__ prefix (mcp__github__get_*); deny and ask rules accept globs anywhere in the tool name (mcp__*). Deny is evaluated first and always wins. A rule with parentheses on an mcp__ tool is skipped.

{
  "permissions": {
    "allow": ["mcp__github__pull_request_read", "mcp__github__list_issues"],
    "deny": ["mcp__github__merge_pull_request", "mcp__github__delete_*"]
  }
}

Allow read tools (list, get, read) and leave write tools on prompt. Servers can also narrow themselves: github-mcp-server takes --toolsets (for example repos,issues,pull_requests). Put shared-server deny rules in the project’s .claude/settings.json to limit blast radius.

Control context and output cost

Tool search is on by default, so MCP tool definitions load on demand rather than all at once; ENABLE_TOOL_SEARCH=false turns it off. Claude Code warns when one tool result exceeds 10,000 tokens and caps results at 25,000 by default (MAX_MCP_OUTPUT_TOKENS raises it). Set MCP_TIMEOUT for slow server startup and a per-server timeout (milliseconds) for slow tools.

Choose MCP or the CLI by what the integration needs

Use a service’s own CLI (gh, aws, gcloud) when one exists and Claude has a shell; Anthropic calls CLIs the most context-efficient way to reach external services. Use MCP when you need typed inputs, managed OAuth, per-tool permissions, or clients without a shell. If the same Bash command appears in three briefs, wrap it in a server or enable an official one.

Before a brief depends on MCP, add a preflight: run /mcp or list tools and stop if the expected tool, such as mcp__github__list_issues, is missing. Servers fail to start from a bad binary path, a bad token, or a network error, and the brief otherwise falls back to Bash silently.

Verify you trust every server. One that fetches external content can carry prompt injection; see prompt-injection-defense.

Backlinks