How to connect Claude Code to tools via MCP

MCP is how Claude Code stops living on pasted context. The Model Context Protocol is an open source standard for AI-tool integrations: MCP servers give Claude Code access to your tools, databases, and APIs. Connect a server 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.

With servers connected you can ask Claude Code to implement a feature from an issue tracker and open a PR, check monitoring data, query a database, update a template from a design, or draft follow-up mail. A server can also push messages into a session so Claude reacts to external events while you are away.

The durable setup is the CLI: claude mcp add, then list, inspect, and remove. This walkthrough follows that official reference.

Use HTTP for remote servers

HTTP is the recommended option for connecting to remote MCP servers, and the most widely supported transport for cloud-based services.

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

Example:

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

With a Bearer token:

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

When you configure servers in .mcp.json, ~/.claude.json, or claude mcp add-json, the type field accepts streamable-http as an alias for http. The MCP specification uses that name for this transport, so configs copied from server docs work without modification.

A JSON entry that has a url but no type is a configuration error. Claude Code reads an entry with no type as a stdio server, skips it, and reports a missing type on that entry. Each claude mcp add and claude mcp add-json command writes to local scope unless you pass --scope project or --scope user. Success prints an Added ... line.

SSE is deprecated

The SSE (Server-Sent Events) transport is deprecated. Use HTTP instead, where available. Some services still expose only an SSE endpoint. Use the same command as the HTTP transport, with the SSE transport option:

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

claude mcp add --transport sse asana https://mcp.asana.com/sse

claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Stdio servers need -- before the launch command

Stdio servers run as local processes on your machine. They are ideal for tools that need direct system access or custom scripts.

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

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

The -- (double dash) separates Claude’s own options, such as --transport, --env, and --scope, from the command that runs the server. Everything after -- is passed to the server untouched. Without --, Claude Code would try to parse the server’s flags as its own options.

--env accepts multiple KEY=value pairs. If the server name comes directly after --env, the CLI reads the name as another pair and rejects it, so place at least one other option between --env and the server name.

Claude Code sets CLAUDE_PROJECT_DIR in the spawned server’s environment to the project root, so the server can resolve project-relative paths without depending on the working directory. This is the same directory hooks receive. Read it from inside the server process, for example process.env.CLAUDE_PROJECT_DIR in Node or os.environ["CLAUDE_PROJECT_DIR"] in Python. The value is the stable project root and does not change when you add or remove working directories mid-session. A server that limits filesystem access to allowed directories should implement the MCP roots/list request instead.

WebSocket: JSON only

WebSocket servers hold a persistent bidirectional connection, which suits remote MCP servers that push events to Claude unprompted. Use HTTP instead when your server only responds to requests: HTTP supports OAuth and claude mcp add --transport, while WebSocket supports neither. The claude mcp add --transport flag does not accept the WebSocket type.

Configure WebSocket servers in .mcp.json or with claude mcp add-json:

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

That entry accepts the same url, headers, headersHelper, timeout, and alwaysLoad fields as http. Authentication is header-only.

WebSocket servers do not appear in claude mcp list output. Use claude mcp get <name> or the /mcp panel.

If the docs were written for another client

Look for a URL, a launch command, or an mcpServers JSON block:

• An https endpoint: add it with HTTP transport, or with SSE transport when the instructions say the endpoint uses SSE. For a wss endpoint, use claude mcp add-json as in the WebSocket section above.
• An npx, uvx, or binary command: put the whole command after --. Pass environment variables with --env after the server name and before --.
• An mcpServers block: pass claude mcp add-json the object inside mcpServers, not the wrapper. If there is a url with no type, add a type that matches the endpoint first. Pick a server name that uses only letters, numbers, hyphens, and underscores.

Example from a stdio JSON block:

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

List, inspect, and remove

claude mcp list

claude mcp get notion

claude mcp remove notion

Within Claude Code, check status with /mcp.

claude mcp add confirms a successful add by printing Added ..., which means the configuration was written. claude mcp list then shows a health status next to each server, such as ✔ Connected, ! Needs authentication, or ✘ Failed to connect. A failure status means Claude Code could not connect to that server, not that the list command failed.

When you remove a remote server, Claude Code also deletes the OAuth tokens and client registration it stored for that server. Toggle a server off in the /mcp panel if you want to stop connecting without losing its configuration.

Trust the server before you connect

Verify you trust each server before connecting it. Servers that fetch external content can expose you to prompt injection risk. Reviewed connectors in the Anthropic Directory use the same MCP infrastructure as Claude Code, so you can add any remote server listed there with claude mcp add.

Next step: pick one remote HTTP server, run claude mcp add --transport http <name> <url>, then confirm it with claude mcp get <name> and /mcp.

Sources

• Connect Claude Code to tools with MCP