Claude Code MCP servers: add one and check it first

Claude Code MCP servers are added with one command, claude mcp add, and HTTP is the recommended transport for remote servers. Before you connect any of them, check that you trust it, because servers that fetch external content can expose you to prompt injection risk.

This guide covers the four ways to add a server, how to convert setup instructions written for another client, the scope a server lives in, the limits that apply, and a short trust check. The reference for every flag is the Claude Code MCP page.

1. Decide if you need a server at all

When should you connect one? When you find yourself copying data into chat from another tool, like an issue tracker or a monitoring dashboard. Once connected, Claude can read and act on that system directly instead of working from what you paste.

If you only paste something once, a server is more setup than it saves. If you paste the same kind of data every day, connect it.

2. Pick the transport

The transport is how Claude Code talks to the server. The source describes four.

Two limits matter. The SSE transport is deprecated, so prefer HTTP where the service offers it. And HTTP supports OAuth and the add command’s transport flag, while WebSocket supports neither, so use WebSocket only when you need pushed events.

3. Add the server

Run the command that matches the transport. These come from the reference, with a placeholder token and key.

# Remote HTTP server (Notion example from the docs)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Remote HTTP server that needs a bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
 --header "Authorization: Bearer your-token"

# Local stdio server; everything after the double dash runs the server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
 -- npx -y airtable-mcp-server

For stdio, the double dash separates Claude’s own options from the command and arguments that run the server. Without it, Claude Code would parse the server’s flags as its own. Also, place at least one other option, such as the transport flag, between the env flag and the server name, or the CLI reads the name as another key-value pair and rejects it.

For SSE, the same HTTP command usually works: Claude Code tries the HTTP transport first and switches to SSE when the server doesn’t accept it. The automatic switch requires Claude Code v2.1.265 or later. On an earlier version, pass the SSE transport flag directly.

WebSocket has no flag. The add command’s transport flag doesn’t accept ws, so configure it with claude mcp add-json:

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

4. Convert setup instructions written for another client

Many servers document setup for Claude Desktop or Cursor and give no Claude Code command. Look for one of three things in those instructions:

For the launch-command case, add-json takes the same command and arguments as an object:

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

Two JSON entries need a repair first. A url with no type fails, because Claude Code reads an entry with no type as a stdio server, so add the type that matches the endpoint. And a key with characters other than letters, numbers, hyphens, and underscores needs a different server name.

5. Choose the scope

The scope decides who gets the server. Each add command writes to local scope unless you add the project or user scope flag.

To share a server with your team, add the project scope flag, or add the entry under the servers key in the project-root .mcp.json and commit it. A committed file is the right place for shared servers, and a personal token is not. Reference the token by name instead, with ${VAR} or ${VAR:-default} in the url, headers, env, command or args value:

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

When the same server is defined in more than one place, Claude Code connects once and uses the whole entry from the highest source. Fields are not merged across scopes.

Project-file servers also pass through an approval step. The reference covers how Claude Code loads and approves that file, so read it before committing one for a team.

6. Check that it connected

A successful add prints an Added ... line, but that only means the configuration was written. Confirm the connection itself.

# List every configured server with its health status
claude mcp list

# Details for one server
claude mcp get notion

# Remove a server
claude mcp remove notion

Inside a session, /mcp shows server status. The list shows a health status next to each server, such as Connected or Needs authentication. A server that needs authentication is not broken. It is waiting for you to sign in.

Removing is clean for remote servers: Claude Code also deletes the OAuth tokens and client registration it stored for that server.

7. Know the limits

Output size and timing are where a working server still surprises people. These are the figures the reference gives.

The warning threshold is fixed, so a server that returns large results needs a narrower query, not a setting. Big tool results spend quota quickly; Claude Code usage limits covers what burns it.

8. Vet the server before you trust it

A connected server can feed content straight into your session, so run through this list first.

If you keep skills next to your servers, sharing one skills repo between Claude Code and Codex shows how to avoid copies.

9. Repeat it for each server

For every new server: pick the transport, add it with the matching command, choose local, user or project scope, confirm the status with claude mcp list, then run the trust list. Remove it with claude mcp remove when you stop using it.

Verdict

Add remote services over HTTP, keep personal tokens in local or user scope, and commit only shared servers to the project file. Treat a successful Added line as a written config, not a working server, and check the status before relying on it. Trust a server only after you know where it comes from and what content it pulls in.

Read the full reference: Claude Code MCP documentation