Claude MCP: Connectors, Claude Code and the API

Claude supports the Model Context Protocol in three separate places, and each one works differently. In the Claude apps you add custom connectors or install desktop extensions. In Claude Code you use claude mcp add and a .mcp.json file. In the API you pass mcp_servers and an mcp_toolset on a request. We checked Anthropic's docs on 31 October 2026.

This page maps the three surfaces so you can pick the right one. It does not repeat the click-by-click setup for Claude Code. That lives in our install an MCP server in Claude Code guide, and we link to it where it applies.

The three surfaces at a glance

The same server can often serve all three. A remote server with a public URL works as a connector, in Claude Code and through the API. A local stdio server works in Claude Code and, packaged as an extension, in Claude Desktop. It does not work through the API connector.

What MCP is, briefly

MCP is an open standard for connecting a model to tools and data. A server exposes tools, and it can also expose resources and prompts. A client, such as Claude, discovers what the server offers and calls it when your request fits. Anthropic created the standard. Because it is open, one server can work with many clients, which is why a server written for Claude often works in other agents too. For a concrete reference server, see our Filesystem MCP profile.

MCP in the Claude apps

The apps have two mechanisms. They look alike from the chat box and they are quite different underneath.

Custom connectors (remote MCP)

A custom connector links Claude to a remote MCP server hosted on the internet. Anthropic's support article says Free, Pro, Max, Ultra, Team and Enterprise plans can use them on Claude, Cowork and Claude Desktop, and that Free users are limited to one custom connector. On Team plans only Owners and Primary Owners can add connectors. Enterprise allows a few additional roles.

On Pro or Max, the steps the article gives are:

1. Go to Customize > Connectors.
2. Click Add, then Add custom connector.
3. Enter a name and the remote server URL, then Continue.
4. Review the detected authentication settings.
5. Choose Sign in now, Sign in when needed, or No sign in.
6. Pick an OAuth client option if one applies.
7. Add fixed request headers, such as an API key or bearer token, if the server needs them.
8. Click Add.

On Team and Enterprise, an Owner adds the connector under Organization settings > Connectors, by clicking Add, hovering over Custom and selecting Web. Members then go to Customize > Connectors and click Connect.

To use it in a chat, click the plus button at the lower left, choose Connectors, and toggle the connector on. To change a connector's settings you remove it and add it again.

How remote connectors run

The article says remote connectors are brokered through your Claude account and run from Anthropic's cloud. That applies to claude.ai, Claude Desktop, Cowork and the mobile apps. The practical effect is that your server must be reachable over the public internet. Servers on private networks need Anthropic's IP addresses allowlisted.

Authentication and credentials

Most connectors use OAuth, so Claude never sees your password. Some use an API key or another fixed credential, which is stored encrypted. On Team and Enterprise plans everyone using such a connector shares that one credential, so use one with limited access. You can revoke access by disconnecting the connector in Claude's settings or in the third-party service.

Limits and warnings

• Research cannot currently use tools from local MCP servers.
• During Research, Claude can call connector tools without asking for approval. Anthropic advises disabling tools that write data.
• Custom connectors are not verified by Anthropic.
• Watch for prompt injection in tool inputs and outputs. A malicious server can hide instructions in what it returns.
• Developers can change tool behavior without notice.
• Only click Allow always for tools you trust to run unsupervised.
• Team and Enterprise owners can disable interactive connector tool calls in Organization settings > Connectors.

Desktop extensions (local MCP)

Claude Desktop can run local servers. The newer packaging is a desktop extension, a .mcpb file. The support article gives these steps for the directory:

1. Go to Settings > Desktop app and select Manage next to Extensions. In the older layout, use Settings > Extensions.
2. Click Browse extensions and choose Install on an Anthropic-reviewed extension.
3. Enter any required settings, such as API keys.
4. The extension is available in your conversations.

For your own .mcpb file, open the same Extensions area, click Advanced settings, find the Extension Developer section and click Install Extension. Then select the file and follow the prompts.

Claude Desktop includes a built-in Node.js environment, so you do not install Node yourself. The article does not say which plans can install individual extensions. It does say that Owners and Primary Owners on Team and Enterprise plans can enable or disable extensions for their organization and upload custom extensions for their team.

The older config file

The remote connectors article mentions that local servers configured through claude_desktop_config.json use your local network, and that they are not available in Cowork or claude.ai. The extensions article we read does not cover that file, so we give no path or example for it. If you maintain one, check Anthropic's current Desktop help for the format.

Choosing between a connector and an extension

Our rule of thumb: use a connector for a hosted service such as a project tracker, and an extension for something that has to touch your own disk. Our profiles of Notion MCP and Linear MCP are examples of hosted servers that suit connectors.

MCP in Claude Code

Claude Code treats MCP as a first-class part of the CLI. The reference page is long, and what follows is the map, not the manual. Step-by-step setup is in our install guide. If you do not have Claude Code yet, start with install Claude Code, and see the Claude Code profile for the product overview.

The add command in three shapes

The docs recommend remote HTTP for remote servers. SSE is marked deprecated, and Claude Code tries HTTP first and falls back to SSE on v2.1.265 or later. Local servers use stdio.

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

claude mcp add --transport sse asana https://mcp.asana.com/sse

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

The double dash separates Claude's own options from the server command. Everything after it goes to the server. WebSocket is not accepted by --transport. For it, and for any config you copy from another client, use claude mcp add-json. A url entry without a type is a configuration error, because Claude Code reads it as stdio and skips it.

Scopes

Where a server is stored decides who sees it. This is the part of Claude Code MCP that people most often get wrong.

Pick a scope with -s or --scope:

claude mcp add --transport http shared-server --scope project https://example.com/mcp

When two scopes define the same server, the docs list this order: local, project, user, then plugin-provided servers, then claude.ai connectors. The whole entry from the winning scope is used, with no field merging. A server in the managedMcpServers managed setting ranks above all of them.

The .mcp.json file

Project scope writes a file you can commit:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

It supports environment variable expansion in command, args, env, url and headers. ${VAR} expands to the value, and ${VAR:-default} gives a fallback. That lets a team commit the file and keep tokens out of it.

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

Two traps from the docs. If a variable is unset and has no default, the server still loads with the literal ${VAR} text, and claude mcp list warns. And for remote url and headers, credential-style variable names such as ANTHROPIC_API_KEY read as empty. Copy the value into a variable with your own name.

Claude Code asks before using .mcp.json servers in interactive sessions. Runs with -p and Agent SDK sessions load them without asking. That asymmetry matters for CI. If you want to block a server, the docs name disabledMcpjsonServers, --setting-sources and --strict-mcp-config.

Managing servers

claude mcp list
claude mcp get notion
claude mcp remove notion
claude mcp login <name>
claude mcp logout <name>
claude mcp reset-project-choices

Inside a session, /mcp shows status, handles authentication, enables or disables servers and reconnects. Status markers include Connected, Needs authentication, Failed to connect, Pending approval, Disabled for this project and Blocked by enterprise managed policy. Disabling a server from /mcp writes to disabledMcpServers in ~/.claude.json.

Authentication in Claude Code

For an OAuth server, add it, then run /mcp and finish the browser flow. For servers that need a fixed callback port or pre-registered credentials, the docs show --callback-port, --client-id and --client-secret. A client secret goes to the keychain on macOS, or a credentials file elsewhere. Another route is headersHelper, a script that prints JSON headers, which the docs say times out after 10 seconds and runs on each connection.

claude mcp remove deletes stored tokens locally but does not revoke them at the server, so run claude mcp logout <name> first. Headless runs with claude -p cannot complete OAuth. Authenticate first in an interactive session or with claude mcp login.

Resources, prompts and claude.ai connectors

Type @ in a prompt to see resources from connected servers next to your files. Reference one with @server:protocol://resource/path, for example @github:issue://123. Connectors you set up in claude.ai also appear in Claude Code. They rank last in precedence, so a server you add yourself with the same URL wins. You can block them all with the ENABLE_CLAUDEAI_MCP_SERVERS=false environment variable, or toggle a connector in /mcp for the current project.

Limits and tuning

Tool search is the default on supported models, and it keeps tool descriptions out of context until Claude needs them. The docs say descriptions and server instructions are cut at 4,096 characters for upfront tools, so put the key details first. If you build servers, that is a design constraint worth knowing. If you build servers, the scaffolding plugin below is the docs' starting point.

Claude Code as a server

claude mcp serve starts Claude Code as a stdio MCP server that other applications can connect to. The command prints nothing on start, because a stdio server speaks over stdin and stdout. The docs show wiring it into Claude Desktop through claude_desktop_config.json. The docs also describe claude mcp add-from-claude-desktop, an interactive import of servers you set up in Desktop.

Building your own

The docs point to a plugin for scaffolding:

/plugin install mcp-server-dev@claude-plugins-official
/mcp-server-dev:build-mcp-server

For skills rather than servers, see our Claude Skills page, which explains how they differ from MCP.

MCP in the Claude API

The API route is the MCP connector. It lets the Messages API call remote servers without you writing an MCP client. It is a beta feature. The docs list two beta headers: mcp-client-2025-11-20 for the current feature, and mcp-client-2026-09-15, which adds tool-list pinning and includes everything in the older header. The earlier mcp-client-2025-04-04 version is deprecated.

What it can and cannot do

• Only tool calls are supported from the MCP feature set. Resources and prompts are not.
• The server must be public over HTTP, with Streamable HTTP or SSE.
• Local stdio servers cannot be connected directly.
• The connector is not covered by zero data retention arrangements. Data exchanged with MCP servers is kept under Anthropic's standard retention policy.
• The server URL must start with https://.

Two parts in a request

A request has a server definition in mcp_servers and a toolset in tools:

curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1000,
    "messages": [{"role": "user", "content": "What tools do you have available?"}],
    "mcp_servers": [
      {
        "type": "url",
        "url": "https://example-server.modelcontextprotocol.io/sse",
        "name": "example-mcp",
        "authorization_token": "YOUR_TOKEN"
      }
    ],
    "tools": [
      {
        "type": "mcp_toolset",
        "mcp_server_name": "example-mcp"
      }
    ]
  }'

The server fields are type (only url today), url, name, and an optional authorization_token. The API enforces that every server is referenced by exactly one toolset and that the name matches. Skip the toolset and the request fails validation.

Allow and deny lists

The toolset decides which tools Claude may use. For an allowlist, disable everything by default and enable named tools:

{
  "type": "mcp_toolset",
  "mcp_server_name": "google-calendar-mcp",
  "default_config": {
    "enabled": false
  },
  "configs": {
    "search_events": {
      "enabled": true
    },
    "create_event": {
      "enabled": true
    }
  }
}

Each tool also takes defer_loading, which keeps its description out of the prompt until tool search needs it. If you name a tool in configs that the server does not have, the API logs a warning but returns no error.

Pinning the tool list

A server can change its tools at any time. With the mcp-client-2026-09-15 header the API records the tool list each server returns, as an mcp_tool_listing block, and lets you copy that list into the toolset's tools field. Then the API stops asking the server and uses your pinned copy. That keeps a server update from changing what Claude sees mid-conversation. The docs mark it as available on the Claude API and as beta.

Getting a token

The API does not run OAuth for you. You obtain the access token and refresh it. For testing, Anthropic's docs suggest the MCP Inspector:

npx @modelcontextprotocol/inspector

In its sidebar choose SSE or Streamable HTTP, enter the server URL, open Auth Settings, run the Quick OAuth Flow and copy the access_token into authorization_token. The Inspector's own README covers the other options.

Models and platforms

The docs list many Claude models as supported, including claude-opus-5-5, claude-sonnet-5-5 and claude-haiku-5-5. Platforms marked beta include the Claude API, Claude Platform on AWS, Claude Models on Google Cloud and Microsoft Foundry. For agent loops, our Claude Agent SDK profile covers the SDK route.

Which route to use

Security notes that apply everywhere

The same risks hold on all three surfaces. A server is code you are letting an AI model call. Anthropic's own warnings say to connect only to servers you trust, to review the permissions requested during sign-in, and to watch for prompt injection. Read-only credentials limit the damage. Claude Code's docs use a read-only database user in their Postgres example for that reason.

We would add one practice of our own: keep the number of connected servers small. Each one adds tools the model must choose among, and each is another party with access to what you send it.

Our take

Think of the three surfaces as three audiences. Connectors serve people who do not want a terminal. claude mcp and .mcp.json serve developers who need project-level control. The API connector serves builders, and its public-URL requirement is the main design constraint.

We did not run these setups for this page. The commands, header names and menu paths come from Anthropic's documentation on 31 October 2026, and menu names in the apps change often, so trust the app if it differs from the list above.

Limits and gotchas

• Free plans get one custom connector.
• Changing a connector means removing and re-adding it.
• Research cannot use local MCP servers.
• The API connector supports tools only, and only for public HTTPS servers.
• .mcp.json servers load without a prompt in -p runs.
• claude mcp remove does not revoke tokens at the server.
• The connector is excluded from zero data retention.