Workbranch › Guides

How to connect MCP servers to Claude Code

MCP servers give Claude Code access to tools outside your code, such as an issue tracker, a database or a design tool. This guide shows the commands to add one, where the setting is saved, how to sign in, and how to tell whether it's working.

Updated 30 October 2026

Commands below follow Anthropic's Claude Code documentation as of October 2026. You run the claude mcp commands in your normal terminal, not inside a Claude Code session.

Add a remote server (most common)

A hosted service gives you a web address for its MCP server, which you'll find in its own setup instructions. Anthropic recommends the HTTP transport for these.

1. In your terminal, cd into the project you'll use it with.
2. Run claude mcp add --transport http notion https://mcp.notion.com/mcp, swapping in your own name and address. The name is what you'll see in lists and in /mcp.
3. If the service uses an API key instead of a sign-in, pass it as a header: --header "Authorization: Bearer your-token".

Older servers may only offer SSE, which is deprecated. Recent versions of Claude Code try HTTP first and fall back to SSE on their own; on older versions use --transport sse.

Add a local server

A local (stdio) server is a program that runs on your computer, often started with npx.

1. Write the Claude options first, then --, then the server's own command: claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server.
2. Claude Code hands whatever follows -- straight to the server program. Without the separator, flags meant for the server (such as -y) are read as Claude Code options.
3. When you use --env, put another option between it and the server name, as in the example, or the name is read as another variable.

Choose a scope

Pick user for tools you want everywhere, such as your notes app, and project for tools the whole team needs in one repository. If one server is defined in several places, Claude Code connects once, in this order of priority: local, project, user, then servers from plugins, then claude.ai connectors. The three scopes are matched by name; plugin servers and connectors count as duplicates when they point at the same address or command. The winning entry is used as a whole; fields aren't combined.

Don't put secrets directly in a shared .mcp.json. It accepts variables such as ${API_KEY} or ${API_BASE_URL:-https://api.example.com}, which each person sets in their own environment.

Sign in to a server that needs an account

1. Start Claude Code with claude.
2. Type /mcp. The panel lists the servers that still need you to sign in.
3. Select the server and follow the browser sign-in. The token is stored on your computer and refreshed for you.
4. Alternatively, from your shell run claude mcp login name. Sign out with claude mcp logout name.

Some services require you to register an app with them first. In that case add the server with --client-id, --client-secret (you'll be asked to type it) and, if their setup asks for a fixed redirect, --callback-port.

Check that it works

• claude mcp list shows every server with its status: Connected, Needs authentication, Failed to connect, Pending approval or Disabled for this project.
• claude mcp get name shows one server's details, including the HTTP error when it fails.
• Inside a session, /mcp shows the same status and lets you reconnect.
• Finally, ask Claude to do something only that server can do, such as "list my open Linear issues".

Remove a server with claude mcp remove name.

Good to know

• Project servers ask first: the first time a session finds servers in a repository's .mcp.json, Claude Code asks you to approve them. Undo your choices with claude mcp reset-project-choices. Only approve servers from repositories you trust.
• Permissions still apply: each MCP tool call can prompt you like any other tool; see how to manage permissions in Claude Code.
• Large results: Claude Code warns when a tool returns more than 10,000 tokens and caps output at 25,000 by default. Raise it with the MAX_MCP_OUTPUT_TOKENS environment variable.
• Plugins: some plugins bring their own MCP servers, so installing a plugin can be an easier route; see how to install plugins in Claude Code.

If it doesn't work

• Failed to connect: run claude mcp get name to see the error, check the URL, then run /mcp reconnect all in a session (recent versions) to retry.
• A slow local server times out at startup: start Claude Code with a longer limit, such as MCP_TIMEOUT=10000 claude (in milliseconds).
• "has a url but no type": a JSON entry for a remote server is missing "type": "http".
• The API key is rejected: Claude Code warns about spaces or line breaks at the start or end of a header. Re-add the server with a cleanly pasted token.

Sources

• Claude Code user FAQ (Claude Help Center, checked 30 October 2026)
• Connect Claude Code to tools via MCP (Claude Code Docs, checked 30 October 2026)

Frequently asked questions