MCP integration in Claude Code

What MCP gives Claude Code#

By default, Claude Code can read your files, run shell commands (in the working directory), edit code, and call the model. That’s the built-in toolset. MCP — the Model Context Protocol — is how you bolt on everything else.

An MCP server is a small program (Node, Python, Go, anything) that exposes a typed set of tools and resources over a standard JSON-RPC protocol. Claude reads the manifest, learns what the tools do, and calls them when the conversation calls for it. The server runs locally (stdio transport) or remotely (HTTP / SSE transport); Claude just sees a tool list.

Why this matters: instead of every IDE-style tool reimplementing “talk to GitHub Issues” or “query Postgres” or “read my calendar,” there’s now one protocol. Write the integration once, plug it into Claude / ChatGPT / Cursor / VS Code Copilot / Copilot Studio — they all speak MCP.

See §MCP.1 What is MCP for the protocol’s why-it-exists explainer.

Three ways to add a server#

Global — in your user-scoped config#

For tools you’ll want in every project. Add them to ~/.claude.json (the root-level file Claude Code uses for user-scoped MCP servers). The easiest way is the claude mcp add CLI:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/sush/Documents

claude mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_TOKEN -- npx -y @modelcontextprotocol/server-github

Or, if you prefer editing the file directly, ~/.claude.json looks like:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/sush/Documents"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

⚠️ Don’t paste raw tokens into JSON. Reference an env var (${GITHUB_TOKEN}) and set the real value in your shell config. ~/.claude.json is not encrypted at rest, and editors / backups / clipboard managers can leak its contents.

Restart Claude Code. The new servers show up in /mcp (the slash command that lists active servers).

Project-scoped — in .mcp.json#

For tools specific to one project — say, a DB connection to that project’s local Postgres. Create .mcp.json at the project root:

{
  "mcpServers": {
    "postgres-local": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost:5432/myapp_dev"]
    }
  }
}

This is checked into the repo (without secrets — load secrets via env vars in your shell, NOT in the JSON). When teammates clone the repo, they pick up the same MCP servers automatically.

Adding from the CLI without editing files#

claude mcp add <name> -- <command> <args...>

Persists the server to ~/.claude.json (or .mcp.json if you pass --scope project). Useful when you want to experiment with a server before deciding whether to keep it.

Useful reference servers#

Anthropic and the MCP community maintain a set of reference servers at github.com/modelcontextprotocol/servers. The currently-active reference servers are: everything, fetch, filesystem, git, memory, sequentialthinking, and time.

Many older “official” servers — github, postgres, sqlite, brave-search, puppeteer, slack, gdrive, redis — have been moved to github.com/modelcontextprotocol/servers-archived. Most are still functional, but day-to-day maintenance has moved to vendor-owned repos (the official GitHub MCP server, for example, now lives at github/github-mcp-server).

Server	What it adds	Where it lives
filesystem	Read/write outside the working directory (e.g. read from ~/Documents)	reference
git	Deep git operations (rebase, cherry-pick, complex logs) beyond the shell tool	reference
fetch	HTTP requests beyond the model’s default web fetch (custom auth, internal endpoints)	reference
time	Reliable timezone math (the model is bad at this without a tool)	reference
memory	A small knowledge graph Claude can read + write across sessions	reference
sequentialthinking	Structured chain-of-thought helper for hard multi-step problems	reference
github	Issues, PRs, repo search across all your GitHub orgs	now at github/github-mcp-server
postgres / sqlite	Query a DB; Claude reads the schema, runs queries, suggests indexes	servers-archived
slack / gdrive / redis / brave-search / puppeteer	Various integrations	servers-archived

Run npx -y @modelcontextprotocol/server-<name> --help to see what each one exposes. For §MCP.2 Official Anthropic MCP servers details the tool surface of each.

⚠️ Community servers are NOT trust-reviewed by anyone. Read the source before installing. An MCP server can do anything a regular npm package can. See §MCP.3 Community MCP servers for the trust gates that actually matter.

What happens when you add a server#

Claude doesn’t auto-load every tool. When you start a session, it sees the tool list (names + descriptions) from each configured server. Tools are invoked on demand — the model decides “this question needs the github tool” and calls it. You see the call in the terminal, can approve / reject (depending on your settings), and the result feeds back to the model.

You can disable an entire MCP server for the current project via the enabledMcpjsonServers / disabledMcpjsonServers settings — useful when you want a server available globally but off for one repo.

Permissions — what gets confirmed#

Claude Code’s behaviour around tool calls is governed by the permissions block in ~/.claude/settings.json (or .claude/settings.json in a project). Two fields:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm test:*)",
      "Read(~/Documents/**)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(rm -rf *)"
    ]
  }
}

• Anything matching allow runs without prompting.
• Anything matching deny is blocked outright (even if Claude tries).
• Everything else prompts you per-call.

The matching is pattern-based. See the settings docs for the full syntax (including how to scope MCP-server tools).

Sensible defaults are good. The danger pattern is allowlisting too broadly (e.g. allowing every Bash(...) call) — that’s the agent equivalent of chmod 777. Don’t.

Common pitfalls#

Symptom	Likely cause	Fix
Server in config but /mcp doesn’t list it	npx couldn’t fetch the package (no network, registry down)	npx -y @modelcontextprotocol/server-X manually; check error
Server lists but tools never get called	Tool descriptions too vague; model doesn’t know when to use it	Edit the server’s tool descriptions OR add a hint in CLAUDE.md
Tokens burn through fast	Server returns huge JSON blobs that fill the context window	Cap tool output (most servers have a maxResults arg)
Claude calls a tool you didn’t expect	No allow/deny rules for this tool — defaults to prompting	Tighten permissions in settings.json
Postgres MCP returns “permission denied”	Connection string user lacks SELECT on the schema Claude is querying	Grant the right perms, OR use a read-only role

What to do next#

• §MCP.1 What is MCP — the protocol’s design + cross-vendor support
• §MCP.2 Official Anthropic MCP servers — the curated set
• §MCP.3 Community MCP servers — where to find them, how to vet them
• §MCP.4 Build your own MCP server — the 30-minute walkthrough
• §CC.6 Slash commands + subagents — the other extension surface