Back

How to Add a Remote MCP Server to Claude Code

A practical guide to adding a remote MCP server to Claude Code: the claude mcp add command, local, project, and user scopes, API key and OAuth authentication, team setup, and troubleshooting.

Kelis Shekhaliya

Existing SaaS API connected to AI agents through an MCP layer with documented tools, authentication, testing, and monitoring

TL;DR

To add a remote MCP server to Claude Code, run <code>claude mcp add --transport http &lt;name&gt; &lt;url&gt;</code>, choosing <code>--scope project</code> for a shared <code>.mcp.json</code> or <code>--scope user</code> for all your projects. Pass API keys with <code>--header</code> or <code>${VAR}</code> references using your own variable names, or sign in to OAuth servers from <code>/mcp</code>. Check status with <code>claude mcp list</code>.

To add a remote MCP server to Claude Code, run claude mcp add --transport http <name> <url> in your terminal, then start Claude Code and open /mcp to check the connection and sign in if the server uses OAuth. Add --scope project to write the entry to a shared .mcp.json file, or --scope user to load it in all of your projects. If the server takes an API key or bearer token, pass it with --header, or reference an environment variable in .mcp.json so the secret stays out of the repository.

This guide is for SaaS founders, CTOs, and API teams who run an MCP server, or are about to, and want developers to use it from Claude Code. It covers the add command, the three configuration scopes, each authentication method, how to share a setup with a team, and what to check when a server will not connect.


Why Claude Code matters for a SaaS MCP server

Claude Code is Anthropic's agentic coding tool. It runs in the terminal, reads and edits code, and can call MCP tools while it works. When your API is available as an MCP server, a developer can ask Claude Code to look up records, create objects, or check status in your product without copying data into the chat.

Claude Code is configured differently from chat apps. Claude.ai and ChatGPT add remote servers through a connector screen; Claude Code uses a CLI command and JSON files on the developer's machine or in the repository. Your setup instructions should give developers a working command, not just a URL. If you also support chat clients, see how to connect a remote MCP server to Claude and ChatGPT, and for the editor side, how to add a remote MCP server to Cursor.


Before you start

  • The server has a reachable URL. Remote servers are added by URL, such as https://mcp.example.com/mcp. A server on localhost only works for the person running it.

  • It speaks Streamable HTTP. Anthropic's documentation recommends the HTTP transport for remote servers. SSE is still accepted, and WebSocket servers can be added through JSON, but HTTP is the option that supports OAuth and the --transport flag.

  • You know the authentication method. No authentication, a header with an API key or bearer token, or OAuth. Each one changes the command.

  • The tools are tested. Confirm that discovery and a few tool calls work before you hand the setup to anyone. Our guide to testing an MCP server with MCP Inspector covers this.


The claude mcp add command

The basic form for a remote server is:

claude mcp add --transport http my-api https://mcp.example.com/mcp

my-api is the name Claude Code shows for the server. Pick something short and recognisable, because it also appears in tool names and in /mcp. Claude Code prints an Added ... line when the command succeeds.

If you already have an mcpServers JSON block written for another client, you can add it as JSON instead:

claude mcp add-json my-api '{"type":"http","url":"https://mcp.example.com/mcp"}'

One detail catches people out here: a JSON entry with a url must also have a type. Claude Code reads an entry with no type as a local stdio server, skips it, and reports a configuration error. Use "type": "http"; Claude Code also accepts "streamable-http" as an alias, so configurations copied from server documentation work as written.


Choose a scope: local, project, or user

The scope decides where the server loads and whether teammates get it.

ScopeLoads inShared with teamStored in
Local (default)Current project onlyNo~/.claude.json
ProjectCurrent project onlyYes, via version control.mcp.json in the project root
UserAll your projectsNo~/.claude.json

Local scope suits personal testing and servers with credentials you do not want in the repository. Project scope is the one to document for teams: claude mcp add --transport http my-api --scope project https://mcp.example.com/mcp creates or updates .mcp.json, which you commit. User scope is for a server one developer wants everywhere, such as their own company's API.

If the same server name is defined in more than one scope with different endpoints, Claude Code warns about the conflict. Keep one definition and remove the others with claude mcp remove <name> --scope <scope>.


How to add a remote MCP server step by step

1. Run the add command

From the project folder, run claude mcp add with the transport, name, URL, and scope you chose. Add any header flags the server needs (see the next section).

2. Check the server status

Run claude mcp list. Each server shows a status such as ✔ Connected, ! Needs authentication, or ✘ Failed to connect. For more detail on one server, run claude mcp get my-api; on a failure it shows the HTTP status or error code on an Issue: line.

3. Sign in or approve in Claude Code

Start claude and type /mcp. For an OAuth server, follow the browser sign-in from there. For a project-scoped server from .mcp.json, Claude Code asks you to approve it before first use in an interactive session; until then it shows as pending approval.

4. Confirm the tools and run a low-impact test

The /mcp panel shows the tool count next to each connected server. Ask Claude Code to call a read-only tool first, such as listing records, before you try anything that writes data.


Authentication options in Claude Code

API keys and bearer tokens in headers

Pass static credentials with --header:

claude mcp add --transport http my-api https://mcp.example.com/mcp \
  --header "Authorization: Bearer ${MY_API_TOKEN}"

In .mcp.json, use environment variable expansion so the file can be committed without the secret:

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

Claude Code expands ${VAR} and ${VAR:-default} in url and headers. Two rules matter when you write setup docs:

  • Use your own variable name. Claude Code deliberately reads certain credential variables as empty in a remote server's URL and headers, including its own keys such as ANTHROPIC_API_KEY, cloud provider credentials, and others like NPM_TOKEN. This stops a project file from sending those credentials to a server it names. A name such as MY_API_TOKEN expands normally.

  • A rejected header does not fall back to OAuth. If you configured an Authorization header and the server rejects it, Claude Code reports the connection as failed. Fix the token, or remove the header to use OAuth.

OAuth

For an OAuth server, the URL is usually enough. Add the server, open /mcp, and complete the sign-in in the browser. Claude Code stores the tokens and refreshes them automatically. It supports servers that use dynamic client registration or a Client ID Metadata Document.

If your authorization server needs pre-registered clients, developers register an OAuth app with a redirect URI of http://localhost:PORT/callback and pass the details when adding the server:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-api https://mcp.example.com/mcp

--client-secret prompts for the secret with masked input. Sign-in has to happen in an interactive session; a claude -p run has no /mcp panel, so authorize first with /mcp or claude mcp login <name>.

Which should you offer? OAuth gives each user their own permissions and avoids long-lived keys on laptops. Header credentials are simpler for internal teams and early testing. Our guide to API authentication for MCP compares API keys, bearer tokens, and OAuth in more depth.


Sharing a Claude Code MCP setup with your team

Commit a project-scoped .mcp.json with environment variable references, never secret values, and document which variables each developer must set. Each teammate approves the server the first time they run claude in the project. A cloned repository cannot approve its own servers: approval settings committed to the project are ignored until the developer trusts the workspace.

Keep the server name stable. Changing it in .mcp.json looks like a new server to Claude Code, so everyone has to approve and, for OAuth, sign in again.


Troubleshooting a remote MCP server in Claude Code

The server is skipped or never connects

Check that the JSON entry has "type": "http" next to the url. Claude Code also warns about hidden leading or trailing whitespace in values such as url and header values, which often comes from pasting a token with a trailing newline. It does not trim them, so edit the value.

Authentication fails with 401

If you set the header from a variable, confirm the variable is set in the shell that starts Claude Code and that its name is not one Claude Code reads as empty. If the server should use OAuth, remove any Authorization header and sign in from /mcp.

A variable is missing

When a referenced variable is unset and has no default, Claude Code still loads the server with the ${VAR} text unexpanded and shows a missing-variable warning in claude mcp list. Set the variable or add a :-default fallback.

Tool calls time out or results are cut off

Add a per-server timeout in milliseconds to the entry, or set MCP_TOOL_TIMEOUT for all servers. Claude Code warns when tool output passes 10,000 tokens and limits it to 25,000 tokens by default; MAX_MCP_OUTPUT_TOKENS raises that limit. Large results are usually a sign the tool should return less, with filters and pagination.

The server connects but its tools are not used

Claude chooses tools from their names and descriptions. Clear names, precise descriptions, and a focused set of tools help it pick the right one. See how to choose which API endpoints to expose as MCP tools.


Adding a 0mcp server to Claude Code

If your MCP server is hosted on 0mcp, you do not need to write the command by hand. Publish a server version, open Setup, and select Claude Code. 0mcp generates the CLI command for your server and its authentication needs. Choose project or user scope, set each environment variable Setup lists, run the command, then start Claude Code, enter /mcp, and approve the connection. Credential values stay in environment variables, out of .mcp.json and source control. The 0mcp Claude Code setup guide has the details.


Final checklist

  • The server URL is public and serves Streamable HTTP.

  • The command uses --transport http and the right --scope.

  • Every JSON entry with a url has "type": "http".

  • Secrets come from environment variables with your own names, not from committed files.

  • claude mcp list shows the server as connected, and /mcp shows its tools.

  • A read-only tool call works before anyone tries a write.

FAQ

01How do I add a remote MCP server to Claude Code?+

Run <code>claude mcp add --transport http &lt;name&gt; &lt;url&gt;</code>, then start Claude Code and open <code>/mcp</code> to check the connection and sign in if the server uses OAuth.

02Where does Claude Code store MCP server configuration?+

Local and user scope servers are stored in <code>~/.claude.json</code>. Project scope servers are stored in <code>.mcp.json</code> at the project root, which you can commit so the team shares the same servers.

03How do I pass an API key to an MCP server in Claude Code?+

Use <code>--header "Authorization: Bearer ${MY_API_TOKEN}"</code> on <code>claude mcp add</code>, or a <code>headers</code> object in <code>.mcp.json</code> that references an environment variable. Use your own variable name, because Claude Code reads some credential variables, such as <code>ANTHROPIC_API_KEY</code>, as empty in remote server headers.

04Does Claude Code support OAuth for MCP servers?+

Yes. Add the server by URL, then complete the browser sign-in from <code>/mcp</code>. Claude Code stores and refreshes the tokens. For servers without dynamic client registration, pass <code>--client-id</code>, <code>--client-secret</code>, and <code>--callback-port</code>.

05Why does my MCP server show as pending approval?+

Project-scoped servers from <code>.mcp.json</code> need approval before first use. Run <code>claude</code> in the project, accept the workspace trust prompt, and approve the server.

06Why is my MCP server skipped in Claude Code?+

A common cause is a JSON entry with a <code>url</code> but no <code>type</code>. Claude Code treats it as a stdio server and skips it. Add <code>"type": "http"</code>.