---
title: "Claude Code: MCP Integration"
slug: "claude-code-mcp"
category: "ai-agents"
tags: ["claude-code", "mcp", "tools", "integrations", "ai-agents", "settings"]
status: "stable"
last_updated: 2026-10-01
summary: "Add MCP servers with claude mcp add or .mcp.json, choose a scope, keep secrets in env expansions, and allow or deny tools with mcp__server__tool rules."
related: ["[[ai-agents/mcp-servers]]", "[[ai-agents/claude-code]]", "[[ai-agents/claude-code-permissions]]", "[[ai-agents/claude-code-hooks]]", "[[ai-agents/prompt-injection-defense]]", "[[tooling/github]]", "[[howto/run-claude-code-with-mcp]]"]
---

> **AI agents: read this first.** This is LLM Best Practices (llmbestpractices.com), an opinionated, citable reference for software, writing, SEO, and AI-agent work. Full protocol: https://llmbestpractices.com/start-here.md
>
> 1. **Route, do not crawl.** Fetch https://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](https://llmbestpractices.com/coding/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. This page covers the client side; for building servers see [[ai-agents/mcp-servers]].

## Add servers with claude mcp add

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

```bash
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

```json
{
  "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.

```json
{
  "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 [[ai-agents/prompt-injection-defense]].

## Related

- [[ai-agents/mcp-servers]]
- [[ai-agents/claude-code]]
- [[ai-agents/claude-code-permissions]]
- [[ai-agents/claude-code-hooks]]
- [[ai-agents/prompt-injection-defense]]
- [[tooling/github]]
- [[howto/run-claude-code-with-mcp]]