MCP setup guide

Claude Code MCP: set up servers, then put them to work

Updated November 17, 20268 min read

Claude Code MCP support lets Claude use outside tools, such as GitHub, Sentry, Notion or your database, through small connector programs called MCP servers. You add one with claude mcp add, choose who it is for with a scope, and check it with /mcp inside a session. This page explains MCP in plain words, gives the exact setup commands, shows real example servers, and covers what to do when one will not connect.

MCP in plain words: a travel adapter for AI tools

Think of a travel adapter. Your laptop charger does not need to know the shape of every wall socket in the world. The adapter handles that, so one plug works everywhere. MCP (Model Context Protocol) is that adapter for AI apps. A service like GitHub builds one MCP server, and any app that speaks MCP, including Claude Code, can plug into it.

Out of the box, Claude Code can read and edit files and run commands in your terminal. Each MCP server you add gives it new tools: read your GitHub issues, look up an error in Sentry, query a database, update a Notion page. Claude decides when a tool is useful, and every tool call still goes through your normal permission settings.

Servers come in two kinds. A remote server lives on the internet and Claude Code talks to it over HTTP, often with a sign-in. A local server is a small program that runs on your own computer, started by a command, and talks to Claude Code over stdio (its standard input and output).

Before adding a server, check whether a command-line tool already does the job. Anthropic notes that tools like gh, aws, gcloud and sentry-cli are more context-efficient than MCP servers, because Claude can run them directly.

Add an MCP server to Claude Code in five steps

  1. 1

    Find the server's address or command

    Remote servers publish a URL, such as https://mcp.notion.com/mcp. Local servers publish a start command, often beginning with npx.

  2. 2

    Pick a scope

    Local (default) is just you in this project. Project shares it with your team through a .mcp.json file. User makes it available in all your projects.

  3. 3

    Run claude mcp add

    In your terminal, run claude mcp add --transport http notion https://mcp.notion.com/mcp, swapping in your server's name and URL.

  4. 4

    Sign in if asked

    Start claude, type /mcp, choose the server and follow the browser sign-in. Claude Code stores the token and refreshes it for you.

  5. 5

    Check it works

    Run claude mcp list to see every server and its health, then ask Claude something that needs the new tool.

The claude mcp add command, piece by piece

Remote server over HTTP (recommended)

claude mcp add --transport http <name> <url>

# with a sign-in header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Local server over stdio

claude mcp add [options] <name> -- <command> [args...]

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

From a JSON snippet

claude mcp add-json <name> '<json>'
  • Put Claude Code's own options (--transport, --env, --scope, --header) before the server name.
  • For local servers, the -- separates Claude Code's options from the server's command. Everything after it goes to the server untouched.
  • Short forms exist: -t for transport, -H for header, -e for env, -s for scope.
  • Server names may only use letters, numbers, hyphens and underscores.
  • SSE servers still work with --transport sse, but Anthropic marks SSE as deprecated. Use HTTP when a server offers it.

Claude Code MCP config scopes

ScopeWho gets itShared through git?Stored in
local (default)You, in this project onlyNo~/.claude.json, under this project
projectEveryone working on this projectYes.mcp.json in the project root
userYou, in every projectNo~/.claude.json
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

If the same server name exists in more than one place, local wins over project, project over user, and user over servers from plugins and claude.ai connectors. Claude Code uses the winning entry as a whole; it does not merge fields between scopes.

What a .mcp.json file looks like

Project-scoped servers live in a .mcp.json file at the root of your project. You can write it by hand. It supports environment variables, so keys stay out of the file you commit:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}
  • ${VAR} is replaced with the variable's value. It works in command, args, env, url and headers.
  • ${VAR:-default} uses the default only when the variable is not set at all.
  • If a variable is missing and has no default, the server still loads with the literal text, and claude mcp list shows a warning.
  • The first time someone opens the project, Claude Code asks them to approve its .mcp.json servers. claude mcp reset-project-choices lets you answer again.

Example MCP servers for Claude Code

There is no official ranking of the best MCP servers for Claude Code, and the right ones depend on the tools you already use. These are servers that Anthropic's own MCP docs use as examples, which makes them a safe place to start:

GitHub

Read issues and pull requests. Remote, at https://api.githubcopilot.com/mcp/, signed in with a personal access token header.

Sentry

Look up production errors and their stack traces. Remote, at https://mcp.sentry.dev/mcp, signed in through /mcp.

Notion

Read and update pages and databases. Remote, at https://mcp.notion.com/mcp.

PostgreSQL via DBHub

Ask questions of a database. Local, run with npx -y @bytebase/dbhub. Use a read-only database user.

Airtable

Work with bases and records. Local, run with npx -y airtable-mcp-server and your API key in --env.

Asana

Tasks and projects. Uses the older SSE transport at https://mcp.asana.com/sse.

HubSpot

CRM records. Remote, at https://mcp.hubspot.com/anthropic, often added at user scope.

Your claude.ai connectors

Connectors you added on claude.ai show up in Claude Code automatically when you sign in with that account.

# GitHub
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

# Sentry (then run /mcp to sign in)
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

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

# PostgreSQL via DBHub (read-only user)
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# Asana (SSE)
claude mcp add --transport sse asana https://mcp.asana.com/sse

Watch out

An MCP server can do whatever its tools allow with the access you give it. Install servers only from sources you trust, give database servers a read-only login, and never paste real keys into a .mcp.json you commit. Our vibe coding security guide covers keys in more depth.

Two more tricks. On macOS or WSL, claude mcp add-from-claude-desktop imports servers you already set up in the Claude Desktop app. And claude mcp serve turns Claude Code itself into an MCP server that other apps can connect to.

Managing your MCP servers day to day

CommandWhat it does
claude mcp listEvery server with its health status
claude mcp get <name>The saved URL or command, scope and settings for one server
claude mcp remove <name>Delete a server and its stored sign-in
claude mcp login <name>Sign in to a server from the terminal
claude mcp logout <name>Clear a server's stored sign-in
/mcpInside a session: status, sign-in, reconnect, enable or disable
/mcp reconnect allRetry every failed or signed-out server

MCP servers can also offer prompts, which appear as commands like /mcp__github__list_prs, and resources you can mention with @, the same way you mention a file.

Troubleshooting Claude Code MCP servers

The server shows as failed in /mcp

Run claude mcp get <name> and check the URL or command for typos. For a local server, run its start command yourself in a terminal: a missing package or a wrong key shows up straight away. Fix it, then use /mcp reconnect <name>.

It keeps asking you to sign in

Claude Code notices a server needs sign-in when it answers with a 401 or 403 error. Open /mcp, pick the server and finish the browser step. If you are on a machine without a browser, claude mcp login <name> prints a link to open elsewhere.

Your flags went to the wrong program

For local servers, anything you want the server to receive must come after --. Without it, Claude Code tries to read flags like --port as its own. Also put --transport stdio between --env and the server name, or the name gets read as another variable.

A project server never loads

Servers from .mcp.json need your approval the first time. If you declined by accident, run claude mcp reset-project-choices and open the project again.

The server is slow to start

Raise the startup timeout for one run with MCP_TIMEOUT=10000 claude, which allows 10 seconds. A single server's tool timeout can be set with a timeout value in its .mcp.json entry.

Tool output is cut off

Claude Code warns when one tool result passes 10,000 tokens and limits output to 25,000 tokens by default. Start with MAX_MCP_OUTPUT_TOKENS=50000 claude to raise the limit, or ask for smaller results.

A tool appears in /mcp but Claude never uses it

Select the tool in /mcp to see its full name. Claude Code leaves out any MCP tool whose full name is longer than 128 characters, because the API would reject it. A shorter server name usually fixes it.

Do MCP servers eat into your usage limits?

Less than they used to. As of November 2026, tool search is on by default: only tool names and server instructions load when a session starts, and the full tool details load only when Claude needs them. Adding servers therefore has a small effect on your context window. Tool results still count, though. Run /context to see what is using space, check /usage for each server's share of your plan, and switch off servers you are not using in /mcp. Our Claude Code pricing guide has more ways to save.

MCP-connected agents in a VibeCodingDeck grid

VibeCodingDeck does not replace or copy your MCP setup. Each pane runs your own Claude Code, so every server you added with claude mcp add, at any scope, is there in every session. What it adds is the room around your agents: up to 12 sessions in one grid on Windows 10/11 or Apple-silicon Macs, alerts when one needs you, a live usage meter, and per-project boards and notes. It can also send your users' Sentry crash reports and GitHub issues straight to an agent. See the Claude Code GUI page and features, or learn the CLI basics first in how to use Claude Code.

MCP questions from Claude Code users

How do I add an MCP server to Claude Code?

+

Run claude mcp add --transport http <name> <url> for a remote server, or claude mcp add <name> -- <command> for a local one. Then open /mcp in a session to sign in and check that it connected.

Where is the Claude Code MCP config stored?

+

Local and user scope servers are stored in ~/.claude.json. Project scope servers are stored in .mcp.json at the project root, so they can be committed and shared.

How do I share MCP servers with my team?

+

Add them with --scope project. That writes .mcp.json, which you commit. Each teammate approves the servers the first time they open the project.

What does the -- mean in claude mcp add?

+

It separates Claude Code's own options from the command that starts a local server. Everything after -- is passed to the server exactly as written.

How do I remove an MCP server from Claude Code?

+

Run claude mcp remove <name>. That deletes the config and its stored sign-in. Run claude mcp list afterwards to confirm it is gone.

Sources

Run up to 12 AI coding agents in one window.

Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.

Get started

Keep reading