MCP

Adding a server

For remote servers, use the HTTP transport. The docs say SSE is no longer recommended and to use HTTP when you can. A server that runs on your own computer uses stdio, and its command goes after --.

# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Local stdio server: options like --transport, --env and --scope go before --
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Management commands

Inside a session, /mcp lets you check status, authenticate, reconnect, and turn servers off. Turning a server off does not delete its configuration.

claude mcp list           # servers and their status
claude mcp get notion     # details for one server
claude mcp remove notion  # remove it
claude mcp login sentry   # OAuth login from the shell
claude mcp logout sentry  # delete stored credentials

Scopes and .mcp.json

• local (default): this project only, and only you. Stored in ~/.claude.json.
• project: stored in .mcp.json at the project root and shared with your team through version control.
• user: available in all your projects. Stored in ~/.claude.json.
• If the same name exists in more than one place, local wins over project, and project wins over user. The whole entry is used; fields are not merged.

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

Authentication and security

• If a remote server returns 401 or 403, it is marked as needing authentication. Pick the server in /mcp and finish the browser steps.
• Project servers from .mcp.json ask for approval in an interactive session. A cloned repository cannot approve itself.
• A server that fetches outside content can be exposed to prompt injection. The official docs warn you to vet a server before connecting it.
• Running remove on a server does not revoke its token at the auth server. Run claude mcp logout first.
• In non-interactive runs (-p), the OAuth flow cannot be shown, so log in from an interactive session first.

How it differs from plugins, skills, and hooks

MCP gives Claude new tools and access to data. A skill is a set of instructions for how to use tools. A hook is a command that runs automatically on an event. A plugin bundles these for installation, so an MCP server can ship inside a plugin.

Real examples

claude mcp add --transport http --scope user notion https://mcp.notion.com/mcp
(in a session) /mcp

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

Common mistakes and when not to use it

• If you leave out -- when adding a stdio server, Claude Code reads the server's own options (such as --port) as its own.
• A JSON entry that has a url but no type is treated as stdio and skipped with an error. Set type to "http".
• Do not connect servers you have not vetted. Outside text the server fetches can read to Claude like instructions.
• If a pasted token ends with a stray newline, you get a warning but it is not trimmed for you. You have to fix the setting by hand.
• Many servers means many tool definitions taking up context. Turn off the ones you are not using in /mcp.

FAQ