Claude Code MCP: add a remote server with claude mcp add

By Killian, founder · Updated 27 October 2026 · Markdown

To add a remote MCP server to Claude Code, run claude mcp add --transport http <name> <url> in your terminal, then start Claude Code, type /mcp, pick the server and authenticate in the browser. That’s the whole setup for an OAuth server. This guide adds scopes (who else gets the server), header-based servers, the .mcp.json file for teams, how to check the tools loaded, and the errors you’re most likely to hit.

The example server is datatomcp, which lets Claude Code query your CSVs and Google Sheets.

1. Add the server

claude mcp add --transport http datatomcp https://app.datatomcp.com/mcp

--transport http is Streamable HTTP, the transport Anthropic recommends for remote servers. SSE (--transport sse) still works but is deprecated; recent versions try HTTP first and fall back to SSE on their own.

Pick a scope

For a personal data source like datatomcp, --scope user means you add it once:

claude mcp add --transport http --scope user datatomcp https://app.datatomcp.com/mcp

Servers that use an API key

If the server expects a header instead of OAuth, pass it with --header:

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

Don’t add an Authorization header to an OAuth server. Claude Code sends it, the server rejects it, and you get a failed connection instead of a sign-in prompt.

2. Sign in

Start claude, run /mcp, choose datatomcp and pick Authenticate. Your browser opens the server’s sign-in page; for datatomcp you log in and approve read access. Back in the terminal the server shows as connected. From the shell you can also run claude mcp login datatomcp, and claude mcp logout datatomcp clears the stored token.

3. Check the tools loaded

claude mcp list

Each server shows a status: ✔ Connected, ! Needs authentication, ✘ Failed to connect or ⏸ Pending approval. Inside a session, /mcp shows the same plus the number of tools per server. claude mcp get datatomcp prints the details, including an Issue: line when something is wrong.

Then ask for something only that server knows:

Use datatomcp to list my datasets, then tell me the top 5 customers by revenue in the orders dataset.

You’ll see the tool calls (mcp__datatomcp__list_datasets, then aggregate) and their results in the transcript.

Sharing a server with your team: .mcp.json

--scope project writes a .mcp.json file you can commit:

{
  "mcpServers": {
    "datatomcp": {
      "type": "http",
      "url": "https://app.datatomcp.com/mcp"
    }
  }
}

Each teammate is asked to approve the server the first time they open the project, and each signs in with their own account, so nobody shares a token. For header-based servers use environment variables, never literal secrets: "Authorization": "Bearer ${API_KEY}". ${VAR:-default} gives a fallback value.

Troubleshooting

• ! Needs authentication. Run /mcp and authenticate. Tokens can expire; the same step renews them.
• ✘ Failed to connect with a 401. You probably set an Authorization header on an OAuth server, or the token in the header is wrong. claude mcp add doesn’t check credentials, so the error only shows when the server connects.
• ⏸ Pending approval. A server from .mcp.json hasn’t been approved yet. Start claude interactively and accept it. claude mcp reset-project-choices resets earlier decisions.
• Same name in two scopes. If datatomcp exists in both local and user scope with different URLs, remove one: claude mcp remove datatomcp --scope local.
• Large results get cut. Claude Code warns above 10,000 tokens of tool output and caps it at 25,000 by default (MAX_MCP_OUTPUT_TOKENS raises it). A better fix is a server that returns less. datatomcp’s aggregate returns only the totals you ask for, so a sum over 100,000 rows is a few bytes.
• Slow server startup. MCP_TIMEOUT=10000 claude gives servers 10 seconds to connect.
• A failed server after a network blip. /mcp reconnect all retries every failed server in recent versions.

Why connect a data server to Claude Code

Claude Code can already read files in your repo. A remote data server is useful when the data isn’t in the repo, is too big to read, or changes: a Google Sheet the ops team edits, a 200 MB CSV export, a list you query from several projects. With datatomcp, Claude Code gets five read-only tools (list_datasets, describe_dataset, query_rows, aggregate, distinct_values) and the totals are computed by a database instead of by reading rows into context.

Create a free account, add a CSV or Google Sheet under Add data, and run the command above. The Google Sheets MCP server guide covers the sheet side in detail.

FAQ

Where does Claude Code store MCP servers? Local and user scope go in ~/.claude.json; project scope goes in .mcp.json in the repo root.

Can I add a server by editing JSON instead of running the command? Yes, edit .mcp.json for project scope. For the other scopes the command is safer, since ~/.claude.json holds other settings too.

Do servers added in Claude Code show up in Claude Desktop? No. Claude Desktop and Claude.ai use connectors on your Claude account; see Claude MCP connectors.

How do I remove a server? claude mcp remove datatomcp, adding --scope if it exists in more than one.

Other clients: Add a remote MCP server to any AI client · Codex · Cursor