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

> Add a remote MCP server to Claude Code: the command, scopes, .mcp.json for teams, OAuth sign-in with /mcp, and the errors you will see.

Source: https://datatomcp.com/guides/claude-code-mcp · By Killian · Updated 2026-10-27

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

```bash
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

| Scope | Flag | Available in | Stored in |
|---|---|---|---|
| Local (default) | `--scope local` | This project, only you | `~/.claude.json`, under the project path |
| Project | `--scope project` | This project, everyone who clones it | `.mcp.json` in the repo root |
| User | `--scope user` | All your projects | `~/.claude.json` |

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

```bash
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`:

```bash
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

```bash
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:

```json
{
  "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](https://app.datatomcp.com/login), add a CSV or Google Sheet under **Add data**, and run the command above. The [Google Sheets MCP server guide](/guides/google-sheets-mcp-server) 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](/guides/claude-mcp-connector).

**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](/guides/add-remote-mcp-server) · [Codex](/guides/codex-mcp) · [Cursor](/guides/cursor-mcp)