# How to add MCP servers to Claude Code: commands, scopes, OAuth

> Add any MCP server to Claude Code: claude mcp add for HTTP and stdio servers, local, project and user scopes, .mcp.json, OAuth sign-in and common fixes.

Page: https://hallwaytest.ai/learn/add-mcp-server-claude-code
Author: Marian Kushnir, Product Manager
Published: November 6, 2026. Last updated: November 9, 2026

**Short answer:** Run claude mcp add --transport http with a name and URL for a remote server, or claude mcp add with a name, then -- and the start command for a local stdio server. Add --scope project to share it through .mcp.json, or --scope user for all your projects. Sign in to OAuth servers with /mcp inside Claude Code, and check the status with claude mcp list.

Claude Code can use tools from any Model Context Protocol (MCP) server: an issue tracker, a database, error monitoring or your own internal API. You add a server with one `claude mcp add` command, choose who else gets it with a scope, and sign in with `/mcp` if the server uses OAuth.

## What an MCP server does in Claude Code

An MCP server gives Claude Code tools it can call directly, so it reads and acts on another system instead of working from what you paste into the chat. Remote servers run somewhere else and you connect to a URL; local stdio servers run as a process on your machine.

## Add a remote HTTP server

Use `--transport http` with a name and the server's URL. The Claude Code docs call HTTP the recommended option for remote servers.

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

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

`--transport sse` still exists, but the docs mark the SSE transport as deprecated: use HTTP when a server offers it.

## Add a local stdio server

Put the server's start command after `--`. Everything before it is for Claude Code (`--transport`, `--env`, `--scope`); everything after it is passed to the server untouched.

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

`--env` accepts several `KEY=value` pairs, so keep another option such as `--transport stdio` between the last pair and the server name; otherwise the CLI reads the name as another pair.

## Choose a scope

The scope decides which projects load the server and whether teammates get it. Add `--scope local`, `--scope project` or `--scope user` to the command; local is the default.

| Scope | Loads in | Shared with team | Stored in |
| --- | --- | --- | --- |
| Local (default) | Current project only | No | `~/.claude.json` |
| Project | Current project only | Yes, through version control | `.mcp.json` in the project root |
| User | All your projects | No | `~/.claude.json` |

A project-scoped server is written to `.mcp.json`:

```json
{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}
```

Keep the `type` field. Claude Code treats an entry with a `url` but no `type` as a stdio server and skips it with a configuration error. To add a server from JSON you already have, use `claude mcp add-json <name> '<json>'`. If the same name exists in several scopes, the local definition wins over project, and project over user.

## Sign in with OAuth

Run `/mcp` inside Claude Code, pick the server and sign in through your browser. Claude Code marks a remote server as needing authentication when it answers `401` or `403`, and stores and refreshes the tokens for you.

From the shell, the same flow is one command:

```bash
claude mcp login <name>
```

Add `--no-browser` to get a URL to open yourself, which also works over SSH. `claude mcp logout <name>` clears the stored credentials, and **Clear authentication** in the `/mcp` menu revokes access.

## Check that the server works

`claude mcp list` shows every server with a health status, and `claude mcp get <name>` shows the details of one.

```bash
claude mcp list
claude mcp get <name>
```

The statuses you will see most:

| Status | Meaning |
| --- | --- |
| `✔ Connected` | Ready; its tools are available |
| `! Needs authentication` | Sign in with `/mcp` or `claude mcp login` |
| `✘ Failed to connect` | The detail after it shows the HTTP status or error |
| `⏸ Pending approval` | A `.mcp.json` server you have not approved yet |

Inside a session, `/mcp` shows the tool count next to each connected server.

## Troubleshooting

Start from the status line, then check these common causes:

- **`✘ Failed to connect` with a 401.** `claude mcp add` saves the configuration without checking credentials, so a placeholder token is accepted and fails later. Fix the header or sign in again.
- **A local server is slow to start.** Raise the startup timeout with `MCP_TIMEOUT`, for example `MCP_TIMEOUT=10000 claude` for 10 seconds.
- **Tool output gets cut off.** Claude Code warns above 10,000 tokens of MCP output and limits it to 25,000 by default; set `MAX_MCP_OUTPUT_TOKENS` to change the limit.
- **A teammate's project server never loads.** It is waiting for approval. They need to run `claude` in the project and approve it.
- **A conflict warning for one name in two scopes.** Remove the extra definition with `claude mcp remove <name> --scope <scope>`.

## Example: add Hallway Test to Claude Code

Hallway Test is a remote HTTP server with OAuth, so one command adds it and no token is needed. It lets Claude Code send a flow it just built to a real person from our in-house team, who runs it while thinking aloud; see [what the usability testing MCP does](https://hallwaytest.ai/usability-testing-mcp).

```bash
claude mcp add --transport http hallwaytest https://mcp.hallwaytest.ai/mcp
```

Add `--scope user` before the name if you want it in every project. Then run `/mcp`, choose `hallwaytest`, sign in with Google and approve the connection. Claude Code gets the Hallway Test tools, among them `create_usability_task`, and slash commands such as `/mcp__hallwaytest__test-usability`.

A new account can connect right away, but the first request to dispatch a test answers with a link to book the free pilot call. After the 30-minute call we activate the account, with no need to reconnect, and results come back within 24 hours. Claude Code then pulls the recording and transcript through the tools and does the analysis itself. After public launch a test costs $29. For the Claude apps, the setup with a custom connector is on [Connect Hallway Test to Claude](https://hallwaytest.ai/connect-mcp).

## Sources

1. [Connect Claude Code to tools via MCP, Claude Code documentation](https://code.claude.com/docs/en/mcp)

## FAQ

**Where does Claude Code store MCP servers?**
Local and user-scoped servers live in ~/.claude.json in your home directory. Project-scoped servers live in .mcp.json at the root of the project, which you can commit so the whole team gets the same servers.

**Which scope should I use for an MCP server in Claude Code?**
Local, the default, for a server you use in one project and do not want to share. Project for a server the whole team should have in that repository. User for a personal tool you want in every project on your machine.

**Why does my server show Pending approval?**
It comes from a project's .mcp.json, and Claude Code asks for approval before using project-scoped servers. Start claude in that folder, accept the workspace trust dialog and approve the server. claude mcp reset-project-choices resets earlier answers.

**How do I sign in to an MCP server from the terminal without opening a session?**
Run claude mcp login with the server name. On a machine without a local browser it prints the authorization URL; open it elsewhere and paste the redirect URL back. claude mcp logout clears the stored credentials.

**Do connectors I added in claude.ai work in Claude Code?**
Yes, if you are logged into Claude Code with a claude.ai account. Connectors added at claude.ai appear in Claude Code automatically, and /mcp lists them next to the servers you added locally.

## Related

- [Home](https://hallwaytest.ai/index.md)
- [Pricing](https://hallwaytest.ai/pricing.md)
- [Book a free pilot](https://hallwaytest.ai/book.md)