MCP
MCP is the Model Context Protocol, an open standard that lets Claude Code use tools, files, and prompts from other programs.
A program that offers them is an MCP server.
For example, claude mcp add --transport http notion https://mcp.notion.com/mcp adds a server over HTTP.
This page covers the big picture. The other pages list every option.
Transports
The transport is how Claude Code talks to a server. Set it with type in the server entry.
Source: Connect Claude Code to Tools via MCP, Control MCP Server Access for Your Organization, and the program (the server schema).
| Transport | Status | What It Does | How It Works |
|---|---|---|---|
stdio | Documented: An official docs page names this item. | Runs a local process. | The default when type is missing. Needs command. Claude Code sets CLAUDE_ in the process env. |
http | Documented: An official docs page names this item. | Talks to a remote server over streamable HTTP. | The recommended remote transport. streamable- is an alias. Supports OAuth and headers. |
sse | Documented: An official docs page names this item. Deprecated: The program or the official docs call this deprecated. Use --transport http | Talks to a remote server over server-sent events. | Deprecated. -- tries HTTP first and falls back to SSE (2. and later). |
ws | Documented: An official docs page names this item. | Talks to a remote server over WebSocket. | Header-only auth, no OAuth. claude mcp add -- does not accept it. Claude Code does not retry the first connect. Use it in ., add-, plugins, and agent files. |
sdk | Documented: An official docs page names this item. | An in-process server of an SDK host. | Only an SDK host can register it. Claude Code skips it in . and settings. |
sse- | Undocumented: Only the program shows this item. It can change without notice. | A server of an IDE extension over SSE. | Has ide and ide. The idle timeout does not apply. |
ws- | Undocumented: Only the program shows this item. It can change without notice. | A server of an IDE extension over WebSocket. | Has ide, auth, and ide. |
claudeai- | Undocumented: Only the program shows this item. It can change without notice. | A claude.ai connector through the MCP proxy. | A config file cannot declare it. Claude Code says type "claudeai-. |
Scopes
A scope says where Claude Code stores a server and who sees it.
| Scope | Status | What It Is | How It Works |
|---|---|---|---|
local | Documented: An official docs page names this item. | A private server for one project. | The default scope. Claude Code stores it in ~/. under projects["<path>"].. |
project | Documented: An official docs page names this item. | A server shared with the team. | Claude Code stores it in . at the project root. Interactive sessions ask for approval. |
user | Documented: An official docs page names this item. | A server for all your projects. | Claude Code stores it in ~/. under mcp. |
| Plugin | Documented: An official docs page names this item. | Servers that a plugin bundles. | Named plugin:. Tools are mcp__. |
| claude.ai connectors | Documented: An official docs page names this item. | Servers you added in claude.ai. | Claude Code fetches it at start for a claude.ai login. It has the lowest precedence. |
managed | Documented: An official docs page names this item. | Servers your organization provides. | From the managed key in managed settings (the managed- file gets the enterprise scope; source: the program). Ranks above every other source (2. and later). |
dynamic | Undocumented: Only the program shows this item. It can change without notice. | Servers passed at run time. | Used for --, for the remote copy from CLAUDE_, and for plugin servers. |
enterprise | Undocumented: Only the program shows this item. It can change without notice. | The servers in managed-. | Read from the managed settings folder. While the file exists, it has exclusive control of MCP servers. Claude Code blocks agent frontmatter servers. Checked: user and project servers did not start. claude mcp list showed only the managed server. claude mcp get showed Scope:. -- failed with You cannot dynamically configure MCP servers when an enterprise MCP config is present. Checked with a user agent that has mcp frontmatter: the agent ran, but its server did not start. A notice said probe-. init listed the managed server with source enterprise. See Probes. |
agent | Undocumented: Only the program shows this item. It can change without notice. | A server in an agent's mcp frontmatter. | Starts when that agent runs and stops when it ends. Claude Code skips project agents (.) in a folder you have not trusted. -- and -- block it. Checked in - with a user agent. |
The full scope list is local, user, project, dynamic, enterprise, claudeai, managed, agent. Plugin servers also use dynamic.
Example
Add three kinds of servers
# Remote server over HTTP
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
# Local server with an env var (use -- before the command)
claude mcp add my-server -e API_KEY=xxx -- bunx my-mcp-server
# Shared with the team through .mcp.json
claude mcp add --scope project files -- bunx @example/files-server
How It Works
Claude Code merges all sources and keeps one entry per name.
Precedence is on the Server Configuration page.
After a server connects, its tools get names like mcp__github__create_issue. See MCP Runtime.
Pages in This Section
| Page | What It Covers |
|---|---|
| Server Configuration | File shape, options per transport, env var expansion, names, precedence |
| MCP Settings and Policy | Settings keys, allow and deny lists, approvals, managed-, flags |
| MCP Commands | Every claude mcp subcommand and flag, and / |
| MCP Runtime | Tool names, resources, prompts, elicitation, channels, limits, recovery |
| MCP Authentication | OAuth, headers, XAA, claude.ai connectors |
| MCP Env Vars | Every MCP env var |
| MCP Settings Keys | The same keys on the settings side |
Related Pages
- Plugins can bundle MCP servers.
- Plugin and MCP Env Vars