MCP in Claude Code

Claude Code is an MCP client: it can connect to MCP servers, programs that give it extra tools for a browser, an IDE, an issue tracker, a database or a docs service. This page covers how to add servers, where their configuration lives, how to allow their tools and what to watch out for.

What it is

MCP support is built into Claude Code. You manage servers with the claude mcp commands in your shell and the /mcp command inside a session. A server is either:

• Remote: runs elsewhere and is reached over HTTP. The http transport is the recommended one; the older sse (Server-Sent Events) transport is deprecated.
• Local: runs as a process on your machine and talks over stdio (standard input and output). Good for tools that need direct access to your system.

Servers also reach Claude Code without claude mcp add:

• Connectors from claude.ai. If you log in to Claude Code with a claude.ai account, the MCP servers you added in claude.ai (called connectors) are available in Claude Code automatically. Turn that off with "disableClaudeAiConnectors": true in settings.
• The Anthropic Directory at claude.ai/directory lists reviewed connectors; any remote server listed there can also be added with claude mcp add.
• Plugins can bundle MCP servers that start when you enable the plugin.

What problem it solves

Without MCP, the agent works only from what you paste: a ticket copied from the tracker, a stack trace copied from monitoring, a page you described in words. Each paste is a copy that goes stale, and the agent cannot look further. With a server connected, it reads the ticket, opens the page or queries the docs itself, and acts there when the server has a tool for it.

How to try it

Add a remote server. DeepWiki is free, needs no login and answers questions about public GitHub repositories:

claude mcp add --transport http deepwiki https://mcp.deepwiki.com/mcp

Add a local server: everything after -- is the command that starts it, passed through untouched:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

Check and manage:

claude mcp list          # every server with a status: connected, needs authentication, failed
claude mcp get deepwiki  # details for one server
claude mcp remove deepwiki

Inside a session, /mcp lists the servers, signs you in to servers that use OAuth, and toggles a server off without losing its configuration.

Scopes

--scope (or -s) decides where the configuration is stored and who gets it:

Scope	Loads in	Shared with the team	Stored in
local (default)	This project only	No	~/.claude.json
project	This project only	Yes, through git	.mcp.json in the project root
user	All your projects	No	~/.claude.json

.mcp.json supports environment variables, so you can commit it without secrets: ${VAR} expands to the variable’s value and ${VAR:-default} falls back to a default.

Permissions

Each MCP tool is named mcp__<server>__<tool>, and permission rules use that name. mcp__deepwiki__* (or just mcp__deepwiki) allows every tool from the deepwiki server; mcp__deepwiki__read_wiki_structure allows one. An allow rule may use a glob only after the full mcp__<server>__ prefix: an unanchored allow rule such as mcp__* is skipped with a warning and approves nothing. (A deny rule with mcp__* does work and removes every MCP tool.) Connector tools from claude.ai are named mcp__claude_ai_<server>__<tool>.

Resources and prompts

• Type @ to reference a server’s resources like files, for example, with the GitHub MCP server connected, @github:repo://abavyka/agentic-dev-wiki/refs/heads/main/contents for a repository’s contents on main. The resource is fetched and attached to your message.
• A server’s prompts show up as commands: the GitHub MCP server’s issue_to_fix_workflow prompt runs as /mcp__github__issue_to_fix_workflow owner repo title description labels assignees, with the arguments separated by spaces.

Usage example

Frontend

You are moving a React app to a new major version of a router library and want to know how the library itself handles a case before you change your code. With DeepWiki connected you ask: “In <owner>/<repo>, how are nested route loaders resolved?” Claude picks DeepWiki’s ask_wiki_question tool, passes the repository and the question, and answers from the library’s documentation and code instead of from memory. Allow mcp__deepwiki__* once so it stops asking for each call.

Backend

A Node API team shares one internal MCP server. Commit .mcp.json with the address and keep the token in each developer’s environment:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Each developer approves the project server once in an interactive session. If the server queries a database, give it a read-only database user in the connection string, so nothing Claude runs can change data.

Who it’s for and when

Anyone who keeps pasting data from another system into the chat. Prefer a CLI when one exists: gh, aws, gcloud or sentry-cli add no tool listings to the context, so the costs guide calls them more context-efficient than an MCP server for the same job. Reach for MCP when there is no CLI or it does not fit, for example a browser or an IDE, and turn off servers you are not using.

Gotchas

• Trust before you connect. A server runs code with access to a system. A server that fetches outside content (web pages, issues, emails) can carry a prompt injection: text written to steer the agent.
• .mcp.json from a repo is code that runs on your machine. Interactive sessions ask for approval before using project servers (claude mcp reset-project-choices resets your answers), but claude -p runs, Agent SDK sessions and cloud sessions load them without asking.
• Results cost context, not the tool list. With tool search, connected servers cost almost nothing until used; a big tool result is what fills the context. Above 10,000 tokens you get a warning, and the default limit is 25,000 (MAX_MCP_OUTPUT_TOKENS).
• The tools are the limit. A server exposes only the actions its author wrote tools for, not the whole API or UI of the service.
• --env right before the name fails. The CLI reads the name as another KEY=value pair. Put another option, such as --transport stdio, between them.
• Tool names over 128 characters are dropped. Claude Code leaves such a tool out, so Claude cannot call it. /mcp shows the full name.

Links

• Connect Claude Code to tools via MCP
• Configure permissions
• DeepWiki MCP server
• MCP: the protocol behind it
• MCP tool search: what servers cost in context
• /usage: each server’s share of your usage

Citations

1. Connect Claude Code to tools via MCP
2. Configure permissions: MCP tool rules
3. Manage costs effectively: reduce MCP server overhead
4. DeepWiki MCP server