How to Add an MCP Server to Claude Code: Commands, Scopes and Fixes

The usual way to connect Claude Code to a tool is to read three different setup pages, copy a command that is slightly wrong for your system, and wonder why nothing shows up. The real process is one command and one check, as long as you know which flavor of server you are adding.

This guide gives you the commands for the three kinds of server, explains the scopes that decide who gets the server, and covers sign-in, safety and the fixes for what goes wrong. If MCP is new to you, start with What Is MCP?.

What you need

Connect a server when you find yourself copying data into the chat from another tool. Once it is connected, Claude can read from that system and act in it directly.

Three kinds of server

Which command you use depends on how the server connects to you.

Remote HTTP server

The basic form is the same for every service:

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

A real example connects Notion:

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

If the server needs a token, pass it as a header:

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

Remote SSE server (deprecated)

The SSE method is deprecated, so use HTTP when the service offers it. If a service only has SSE, the command uses a different transport:

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

Local stdio server

A stdio server is a program that runs on your own machine, started by Claude Code. The basic form has a double dash, and everything after it is the command that starts the server:

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

An example that adds an Airtable server with an API key:

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

Check that it worked

After you add a server, check it from your terminal or from inside Claude Code.

$ claude mcp list$ claude mcp get notion$ claude mcp remove notion

Inside a session, type /mcp to see the status of each server. You will see one of three states: connected, needs authentication, or failed to connect.

Sign in with OAuth

Many cloud servers use OAuth 2.0, the "sign in with your account" flow. The simplest path has two steps.

From the shell you can also run claude mcp login <name> and claude mcp logout <name>. Tokens are stored securely and refreshed automatically. To revoke access, use Clear authentication in the /mcp menu.

Scopes: who gets the server

When you add a server, you choose its scope. The scope decides which projects see it and whether your team shares it.

Choose one with the --scope flag:

# Project scope: shared with your team
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# User scope: available in all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

A project-scoped server writes a .mcp.json file at the root of your project, which you commit so everyone gets the same connection:

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

If the same server name appears in more than one scope, Claude Code connects once, using the definition from the highest-precedence source: local first, then project, then user.

When you open a project that has a .mcp.json from someone else, Claude Code asks for your approval before using its servers in an interactive session. To reset those approval choices, run claude mcp reset-project-choices.

Popular servers you can add today

These examples come from the official documentation. Always read the service's own page for the current address.

For the database, notice the user name: readonly. Give Claude a database account that can only read. That one choice removes the most expensive mistake you could make.

You can also browse reviewed connectors in Anthropic's directory at claude.ai/directory. And if you added a connector in claude.ai, it is already available in Claude Code when you sign in with your Claude account.

Stay safe

An MCP server gives Claude access to a system, and some servers fetch content from outside, such as web pages or tickets written by strangers.

That last point connects to how much Claude does without asking. See Claude Code Permission Modes and Plan Mode, Explained to decide it.

Inside Claude Tutorial

Trusting a tool is a decision, not a default

Judging which systems deserve access, and for which actions, is a skill that applies well beyond code, and the app practices it with real scenarios.

Coming Soon

Download on theApp Store

GET IT ONGoogle Play

Limits and tuning

Two limits help explain behavior that otherwise looks odd.

• Large results. Claude Code shows a warning when a tool's output passes 10,000 tokens, and limits output to 25,000 tokens by default. To raise the limit, set the MAX_MCP_OUTPUT_TOKENS variable, for example MAX_MCP_OUTPUT_TOKENS=50000.
• Slow servers. To change how long Claude Code waits for a server to start, set MCP_TIMEOUT. For example, MCP_TIMEOUT=10000 claude allows ten seconds.

Tool search is on by default, so your context does not fill with every tool description at once. Run /context to see what is using space.

When it does not work

When none of that fits, ask Claude Code to help: paste the error and ask what it means. Running /doctor also checks your setup.

Frequently asked questions

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 run /mcp inside Claude Code to check its status and sign in.

Where does Claude Code store MCP servers?

Local and user scope servers are stored in ~/.claude.json. Project scope servers are stored in a .mcp.json file at the root of your project, which you can commit.

What is the difference between local, project and user scope?

Local applies to the current project and only to you. Project applies to the current project and is shared with your team. User applies to all your projects and only to you.

How do I remove an MCP server?

Run claude mcp remove <name>. To sign out of a server without removing it, use claude mcp logout <name>.

What does the double dash mean in claude mcp add?

It separates Claude Code's own options from the command that starts the server. Everything after it is passed to the server untouched.

Are MCP servers safe?

Only as safe as the servers you choose and the access you give. Use trusted servers, read-only database accounts, and a permission mode where you can see what Claude does.

Can I use my claude.ai connectors in Claude Code?

Yes. Connectors you add in claude.ai are available in Claude Code, in the terminal and in cloud sessions, when you sign in with your Claude account.

Your Claude Code MCP checklist

Continue reading

• What Is MCP? The Model Context Protocol Explained Simply for the idea behind it.
• How to Add Connectors in Claude: Directory, Custom URL and Safety for the same thing in the Claude apps.
• Claude Code Best Practices: Habits That Get Better Results for working well once the tools are connected.
• CLAUDE.md Explained: Teach Claude Code Your Project Once to tell Claude how to use the connected tools in your project.