Claude Code MCP: add, manage and secure MCP servers

What MCP gives Claude Code

MCP, the Model Context Protocol, is an open standard for connecting AI tools to outside systems. An MCP server exposes tools, and once you connect one, Claude Code can call them: read issues from your tracker, query a database, drive a browser, check error reports.

To add one, run claude mcp add in your terminal with a name and either a URL (remote server) or a launch command (local server). A good time to connect a server is when you notice yourself copying data from another tool into the chat. Once it is connected, Claude reads that system directly.

How do you add an MCP server?

You add an MCP server with claude mcp add, in one of two common shapes depending on where the server runs.

Remote server over HTTP

HTTP is the recommended transport for remote servers.

# Basic syntax
claude mcp add --transport http <name> <url>

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

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

Local server over stdio

A stdio server runs as a process on your machine. Everything after -- is the command that starts the server; everything before it is for Claude Code.

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

# Example: a server that needs an API key
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

The -- matters. Without it, Claude Code tries to read the server's own flags, like -y or --port, as its own options.

Transports at a glance

Add from a JSON block

Many servers publish setup instructions for other clients as an mcpServers JSON block. Pass the object inside it, not the wrapper, to claude mcp add-json:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

If the entry has a url but no type, add "type": "http" first. Claude Code reads an entry without a type as a local stdio server.

What are MCP server scopes?

Every server is saved at one of three scopes: local, project or user. Pass --scope to choose; the default is local.

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

# Available in every project for you
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

A project-scoped .mcp.json looks like this:

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

Keep secrets out of committed files with environment variable expansion. .mcp.json supports ${VAR} and ${VAR:-default} in command, args, env, url and headers:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

If the same server name exists at several scopes, local wins over project, and project over user. The whole entry from the winning scope is used; fields are not merged.

Manage your servers

# List servers with a health status for each
claude mcp list

# Details for one server
claude mcp get notion

# Remove a server (also deletes its stored OAuth tokens)
claude mcp remove notion

# Sign in to a server from your shell
claude mcp login sentry

Inside a session, /mcp opens the server list. From there you can see each server's status, sign in through the browser for servers that use OAuth, clear authentication, and toggle a server off without deleting its config. claude mcp list shows statuses such as ✔ Connected, ! Needs authentication and ✘ Failed to connect.

For a remote server that needs sign-in, add it and then authenticate:

1. Run claude mcp add --transport http sentry https://mcp.sentry.dev/mcp.
2. Start Claude Code and type /mcp.
3. Pick the server and follow the browser sign-in. Tokens are stored and refreshed for you.

Useful servers you can add today

These commands come from the Claude Code docs or the server's own README. Check each project's page for current options before you connect.

For GitHub, create a fine-grained personal access token limited to the repos Claude should touch. For databases, put a read-only user in the connection string so Claude's queries cannot change data. You can browse more reviewed servers in the Anthropic Directory; any remote server listed there can be added with claude mcp add.

Also consider whether you need a server at all. If a service has a good CLI, such as gh for GitHub, Claude can often use it directly with less setup and less context.

MCP prompts become commands

Servers can also expose prompts. They show up in the / menu as /servername:promptname (MCP), and you can run them as /mcp__servername__promptname with arguments after a space, such as /mcp__github__pr_review 456. See the slash commands guide for how they sit alongside built-in and custom commands.

Do MCP servers use up context?

Adding MCP servers is much cheaper than it was, but not free. Every connected server used to add all of its tool definitions to your context. Claude Code now uses tool search by default: only tool names and server instructions load at session start, and full definitions load when Claude needs a tool. Run /context all to see how many tokens each loaded MCP tool uses, and disconnect servers you are not using.

Security

MCP servers can read and change real systems, so treat each one like a dependency with access to your accounts.

1. Only connect servers you trust. A server that fetches outside content, such as web pages or tickets written by strangers, can carry prompt injection that tries to steer Claude.
2. Use least privilege. Scope tokens to the repos or projects needed, and use read-only database users.
3. Keep credentials local. Use local or user scope for servers with personal tokens. In committed .mcp.json files, reference secrets with ${VAR} instead of writing them in.
4. Review project servers. In interactive sessions, Claude Code asks before using servers from a repo's .mcp.json. In claude -p and SDK runs it cannot ask, so it loads them. Read .mcp.json before scripting Claude over a repo you did not write. claude mcp reset-project-choices clears your past approvals.
5. Control tools with permissions. Permission rules name MCP tools as mcp__<server>__<tool>. Allow mcp__github__get_* for read tools only, or deny mcp__* to block every MCP tool. Subagents can also be limited to specific servers with their tools and mcpServers fields.

Teams that need central control can manage the allowed server list through managed settings, covered in the docs on managed MCP configuration.

MCP vs skills

MCP servers and skills solve different problems, and the best setups use both.

MCP gives Claude the ability to reach a system. A skill tells Claude how your team wants that system used: your schema and query patterns, your ticket format, your release steps. The skills vs MCP guide goes deeper on the trade-offs. If you want to ship servers, skills and hooks together, plugins bundle them into one install.

Kipt stores the skill side of that pairing. Keep the prompts and skills that explain how to use your tools in a private GitHub repo you own, turn a good prompt into a SKILL.md with Promote to skill, and install the lot on any machine with npx skills add https://github.com/<you>/<repo>.git.

Sources: Connect Claude Code to tools via MCP, Extend Claude Code, and the Playwright MCP README.