How to add MCP servers to Claude Code (step by step)

An MCP server gives Claude Code new abilities: query a database, drive a browser, read your tickets. Adding one takes a single command. This guide covers the three kinds of server, where the config lives and how to keep it safe. If you want the background first, read what is MCP.

The three kinds of server#

1. Add a remote (HTTP) server#

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

For example, a hosted server:

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

If it needs a token in a header:

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

Many remote servers use OAuth instead. Add the server, then run /mcp inside Claude Code and follow the sign-in flow, or from the shell:

claude mcp login <name>

2. Add a local (stdio) server#

A stdio server is a program Claude Code starts on your machine:

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

The -- matters. Everything after it goes to the server untouched, so flags like -y are not parsed as Claude Code options. Put your own options (--env, --scope, --transport) before the name.

You can register the server you built yourself the same way. In the MCP in Depth course that looks like:

claude mcp add repopilot -- npx tsx /absolute/path/to/server.ts

3. Pick a scope#

claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http shared-server --scope project https://example.com/mcp
claude mcp add --transport http my-crm --scope user https://crm.example.com/mcp

If the same name exists in several scopes, local beats project beats user. Servers from a shared .mcp.json require your approval before they run in an interactive session, which is a useful guard against a repo adding one behind your back.

4. The .mcp.json file#

Project-scoped servers live in a file you commit:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    },
    "database-tools": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub"],
      "env": { "DB_URL": "postgresql://readonly:pass@host:5432/analytics" }
    }
  }
}

Do not commit real secrets. Use environment variables for tokens and passwords.

5. Manage your servers#

claude mcp list          # everything configured
claude mcp get notion    # details for one server
claude mcp remove notion # remove it

Inside a session, type /mcp to see connection status, sign in with OAuth, enable or disable servers and check which tools they offer. Run /context to see how much context the loaded tools use.

Keep the context small#

Each server adds tool names to the model's context. Claude Code defers the full tool schemas until a tool is needed, so idle servers are cheap, but a dozen overlapping servers still make tool selection worse. Keep the ones you use weekly and remove the rest. Picks to start with: best MCP servers for developers.

Safety checklist#

• Trust the server. Read its code or use a well-known publisher. Local stdio servers run with your user's permissions.
• Treat fetched content as untrusted. A server that returns web pages or issues can carry prompt injection.
• Least privilege. Use read-only database users and narrow tokens.
• Prefer user or local scope for personal tooling, and project scope only for servers the whole team should have.

Official reference: Connect Claude Code to tools via MCP.