Add your first MCP server to Claude Code

An MCP server gives Claude Code access to an outside tool, database or service, so you do not have to paste that data into the chat. Adding one takes a single command.

Two commands to know

For a remote server, use HTTP. This is the documentation's example for Notion:

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

For a program that runs on your own machine (stdio), put -- between Claude Code's options and the server's own command:

claude mcp add --transport stdio myserver -- python server.py --port 8080

Everything after the -- goes to the server unchanged. Put Claude Code's options (--transport, --env, --scope, --header) before the server name. SSE servers exist but are deprecated, so use HTTP where the server offers it.

Look after what you added

• claude mcp list shows your servers.
• claude mcp get notion shows one.
• claude mcp remove notion removes it.
• /mcp inside Claude Code shows the status of each server and handles sign-in.

Three scopes

• Local (default)Stored in ~/.claude.json under the project's path. Only you, only this project.
• ProjectStored in .mcp.json at the project root. Meant to be committed so the team shares it, and Claude Code asks for approval before using it.
• UserStored in ~/.claude.json. Only you, in all your projects.

Choose with --scope. If the same name exists in more than one place, local beats project, which beats user, and Claude Code uses the whole entry from the winner without merging fields.

A shared .mcp.json

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

In this file, ${VAR} is replaced by the value of an environment variable, and ${VAR:-default} uses the default only when the variable is unset. That works in command, args, env, url and headers, so the committed file can name a variable instead of containing a secret.

Signing in

For a server that uses OAuth, run /mcp and finish the login in your browser. Claude Code stores the token and refreshes it. "Clear authentication" in the same menu revokes it. A non-interactive run (claude -p) cannot do the login, so sign in from an interactive session first.

Before you trust one

• Check that you trust the server. The documentation warns that servers which fetch outside content can expose you to prompt injection, which means text on a page or in a document trying to steer Claude.
• In an interactive session Claude Code asks you to approve project servers from .mcp.json. claude mcp reset-project-choices resets your answers.
• Non-interactive runs load project servers without asking, so look at the .mcp.json of any repository you did not write.
• A token you pass with --env or --header is saved as part of that server's configuration. Prefer a variable where the server allows it.

Size and cost

Claude Code warns when one tool result is over 10,000 tokens, and caps results at 25,000 by default. You can raise the cap with the MAX_MCP_OUTPUT_TOKENS variable, but large results fill your context fast. Tool search is on by default, so tool definitions load on demand. If you want fewer tokens used, see spend less of your quota.

Check it works

1. Add one server you trust.
2. Run claude mcp list and /mcp and look for it connected.
3. Ask Claude something only that server can answer.
4. Remove it if you do not use it. An unused server is clutter.

Limits

• Commands, flags and defaults change between versions. Several behaviours on the documentation page depend on a minimum version, so check yours with claude --version.
• We have not tested every server. Whether a given server is safe or works is for you to check.

This follows Anthropic's MCP documentation as we read it in October 2026. We are not affiliated with Anthropic. We wrote this from the documentation and have not tested every example.

If you want a second pair of eyes on your CLAUDE.md and settings, the Tune-Up Kit is a checklist for exactly that.