How to add an MCP server to Claude Code

Adding a remote server over HTTP

A remote server is a URL. Claude Code speaks streamable HTTP to it, so the whole registration is one line:

claude mcp add --transport http hosttracker https://mcp.host-tracker.com/mcp

The first argument after the transport is the name you will see in /mcp and in tool names; the second is the endpoint. Servers that authenticate with OAuth need nothing more on the command line: the first time you open /mcp, select the server and Claude Code opens the browser for the sign-in and consent step, then stores the resulting token and refreshes it on its own. From Claude Code 2.1.186 you can also run the sign-in without the interactive session, with claude mcp login hosttracker, and add --no-browser on a machine with no browser to get a URL to paste elsewhere.

Servers that expect a static token instead take it as a header:

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

A few older servers still speak the SSE transport. It is deprecated in favour of HTTP, and since Claude Code 2.1.265 --transport http tries HTTP first and falls back to SSE if the server refuses, so you rarely need --transport sse any more.

Adding a local server

A local server is a program Claude Code starts for you and talks to over standard input and output. Put its command and arguments after a double dash so Claude Code's own flags are not confused with the server's:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

Environment variables the server needs go through --env (short form -e), repeated once per variable. One documented catch: the option parser reads whatever follows --env KEY=value as another pair, so do not put the server name directly after it; place another option in between or put --env before --transport:

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

If you already have the server's configuration as JSON, for example from its README, claude mcp add-json <name> '<json>' takes it as is, including type, command, args and env.

Choosing a scope: this project, the team, or everywhere

By default a server is added in the local scope, which means this project only and stored in your own ~/.claude.json. Two other scopes exist:

• --scope project writes the entry to a .mcp.json file in the repository root. Commit it and every collaborator gets the same server; Claude Code asks each person to approve it the first time.
• --scope user makes the server available in every project on your machine, still private to you.

When the same name exists in more than one scope, local wins over project, and project wins over user. The whole entry is taken from the winning scope; fields are never merged across scopes. A sensible split is --scope user for services tied to your own account, such as a monitoring or ticketing server, and --scope project for tooling the whole team should share.

Checking that it works

Run claude mcp list outside a session. Each server prints one of a few statuses: connected, needs authentication, failed to connect (with the HTTP status or error appended since 2.1.219), pending approval for an unapproved project server, or disabled for this project. Inside a session, /mcp shows the same servers with their tool counts, lets you start the sign-in for one that needs it, clear its authentication, or disable it for the current project without removing it.

A quick functional test is a request that can only be answered by the server. With the HostTracker server connected, ask "which of my monitors are down right now?" or "run an HTTP check on example.com from three locations"; the assistant should call a tool named after the server and quote a result it could not have known. If nothing happens, the tool list is usually the reason: /mcp shows zero tools for a server that connected but failed authorization.

Removing, inspecting and importing

claude mcp get <name> prints one server's full configuration and scope. claude mcp remove <name> deletes it along with any stored OAuth tokens. If you set servers up in Claude Desktop first, claude mcp add-from-claude-desktop imports them interactively; it works on macOS and on Windows Subsystem for Linux, not on native Windows or native Linux, and skips a Desktop server whose name contains characters Claude Code does not allow (only letters, digits, hyphens and underscores).

A monitoring server as the first test

A monitoring service is a good first server to wire up because the result of a tool call is immediately verifiable: the assistant says a site is up, and you can open it. HostTracker's server needs no local install, authenticates with OAuth in the browser, and exposes instant checks from 300 or more locations plus the monitors, incidents, maintenance windows and status pages on your account, so "is production up?" gets answered from real checkpoints rather than from training data. The related guide on .mcp.json configuration and troubleshooting covers the file format, environment variables and the failures that show up in practice.