Claude Add MCP: Add a Server to Claude Code [2026]

Add an MCP server with the Claude Code CLI

The claude add mcp workflow is the fastest way to connect Claude Code to a tool, but the command has one detail worth getting right from the start: tell it which transport the server uses. A local command is normally a stdio server. A URL is normally an HTTP server. Those are different configuration shapes, and Claude Code will not infer HTTP just because the argument looks like a URL.

This guide uses the current Claude Code CLI syntax, then shows how to inspect what it saved. The commands are useful for one-off local tools, remote services with sign-in, and project configuration that your team can review. To choose a server before adding it, start with the MCPVault server directory, where listings include quality signals and client compatibility.

Choose the right transport before you add anything

MCP has several transports. For a Claude Code setup, the practical split is simple:

| Server type | When to use it | Claude Code flag | What Claude Code stores | |---|---|---|---| | Local stdio | The server runs as a command on your machine | default, or --transport stdio | command, args, and optional env | | Remote HTTP | The server exposes a web endpoint | --transport http | type: "http" and a url | | Remote SSE | A server still exposes the older SSE endpoint | --transport sse | an SSE endpoint configuration |

Anthropic's official MCP documentation recommends HTTP for remote cloud services and documents all three options. That distinction matters because a local process and a remote endpoint have different security boundaries. A local stdio server inherits access from the machine and project where it starts. A remote server can require an OAuth browser flow or an authorization header.

For a local MCP server, the shape is:

claude mcp add my-local-tool -- npx -y my-mcp-server

Everything after -- belongs to the MCP process, not the Claude Code command. If the process needs an environment variable, pass it explicitly rather than placing a secret in source control:

claude mcp add my-local-tool -e API_KEY=replace_me -- npx -y my-mcp-server

For a remote HTTP server, use an explicit transport:

claude mcp add --transport http my-remote-tool https://service.example.com/mcp

The command name is only your local label. It is not proof that the endpoint is safe, maintained, or owned by a particular vendor. Check the repository, authentication method, and maintenance signals first. MCPVault's quality grade documentation explains how the vault separates those signals instead of treating every GitHub result as equivalent.

The URL-as-stdio trap, reproduced

On 2026-08-28, MCPVault tested the current @anthropic-ai/claude-code CLI in an isolated temporary project. We intentionally passed an HTTPS endpoint without --transport:

npx -y @anthropic-ai/claude-code@latest mcp add \
  --scope project example-http https://example.invalid/mcp

The CLI accepted the command, but warned that the URL was being interpreted as a stdio server. Its generated .mcp.json used this shape:

{
  "mcpServers": {
    "example-http": {
      "type": "stdio",
      "command": "https://example.invalid/mcp",
      "args": [],
      "env": {}
    }
  }
}

That configuration cannot launch a web URL as a local process. Running the same test with --transport http produced type: "http" plus a url field, which is the expected remote-server configuration:

npx -y @anthropic-ai/claude-code@latest mcp add \
  --scope project --transport http \
  example-http-correct https://example.invalid/mcp

This is a small but important failure mode. The command can appear to succeed because it wrote a configuration entry, while the next Claude Code session has nothing executable to start. If you are adding a URL, always include --transport http unless the server documentation specifically says SSE.

Pick the configuration scope deliberately

Claude Code supports local, project, and user scopes. The default is local. Scope determines who receives the configuration and whether it belongs in your repository.

| Scope | Good for | Caution | |---|---|---| | local | Personal tools for one checkout | Not shared with teammates | | project | A non-secret server the whole repository needs | Review the generated .mcp.json before committing | | user | A personal tool you use across projects | Do not put project-specific assumptions in it |

For a shared server that does not contain credentials, use project scope:

claude mcp add --scope project --transport http docs-service \
  https://service.example.com/mcp

For a personal tool you use in every checkout, use user scope:

claude mcp add --scope user my-personal-tool -- npx -y my-mcp-server

Project scope is not a reason to commit tokens. Keep secrets in the environment or use the server's OAuth flow. A committed project configuration says, in effect, that everyone who trusts this repository may be asked to run that integration. Review it with the same care you would give any other developer-tool dependency.

Verify the entry before relying on it

After adding a server, inspect Claude Code's configured servers:

claude mcp list

For a named server, inspect its stored details:

claude mcp get my-remote-tool

The command-line result is the first check, not the last. Start a Claude Code session and use /mcp to inspect status, approve the server if Claude asks, and complete sign-in when required. A remote service may be correctly configured but still unavailable because its account authorization has not been completed.

If the service requires OAuth, follow its provider-specific setup notes. Anthropic documents flags for a fixed callback port and client credentials in its MCP connection guide. Match any registered redirect URI exactly. A mismatch between the port or host you registered and the client configuration is an authentication problem, not an MCP transport problem.

For a concrete server candidate, the Context7 listing for Claude Code tracks Claude Code as a compatible client and links to the upstream project. Treat that listing as a discovery and comparison starting point, then use the maintainer's install instructions for the command you actually run.

Add headers only when the server documents them

Some remote MCP services use a bearer token or another request header. Claude Code supports headers on the add command:

claude mcp add --transport http private-tool https://service.example.com/mcp \
  --header "Authorization: Bearer replace_me"

Do not paste a long-lived production credential into a project config just because the command accepts it. Prefer the provider's OAuth flow when it exists. If a token is unavoidable, use a narrowly scoped credential and make sure it is stored outside the repository. The official documentation distinguishes authentication setup from the transport choice, and that separation is useful when debugging.

The same principle applies to local servers. Before running an npx, uvx, Docker, or binary command through Claude Code, read the upstream installation instructions and understand which directories, network services, and environment variables it needs. A server's ability to connect is not the same as a reason to grant it access.

At the midway point of your selection process, use the vault to compare alternatives rather than adding the first package search returns. Prefer clear documentation and an actively maintained upstream project.

A practical troubleshooting sequence

When a new server does not work, avoid changing several things at once. Check these in order:

1. Run claude mcp list and confirm the server name appears.
2. Run claude mcp get <name> and check that the transport matches the server's documentation.
3. For a URL, confirm the entry says HTTP or SSE, not stdio.
4. For a local tool, run the underlying command separately if its maintainer documents a standalone check.
5. Open Claude Code, use /mcp, and complete any pending approval or OAuth browser step.
6. If the server is project-scoped, inspect .mcp.json for accidental credentials or a configuration that should not be shared.

This sequence narrows the problem quickly. A missing entry is a configuration issue. An entry with the wrong transport is a command issue. A healthy entry that asks for sign-in is an authentication issue. Keeping those categories separate saves time and avoids weakening your setup just to make a connection test pass.

Frequently Asked Questions

What is the basic Claude add MCP command?

For a local stdio server, use claude mcp add <name> -- <command>. For a remote endpoint, use claude mcp add --transport http <name> <url>. The transport flag is necessary for HTTP because the default is stdio.

Where does Claude Code save MCP server configuration?

It depends on scope. A project-scoped server is saved in the project's MCP configuration, while local and user scopes are personal configuration. Use claude mcp get <name> and inspect the project file when you need to verify the saved shape.

Does Claude Code support remote MCP servers?

Yes. Claude Code supports remote HTTP and SSE servers. HTTP is the recommended remote transport in Anthropic's documentation. Remote services can still require a sign-in or headers after the configuration entry has been created.

Why does my MCP URL show up as a command?

You probably omitted --transport http. The Claude Code CLI defaults to stdio, so it can save the URL as a local command even while displaying a warning. Remove the incorrect entry and add it again with the explicit HTTP transport.

How can I tell whether a server is trustworthy?

Read the upstream project and the provider's authentication requirements first. In MCPVault, verified listings indicate that a live MCP handshake has passed, while grades summarize maintenance, adoption, license clarity, and documentation signals. Neither replaces a review of the permissions you grant.

---

Your server in the vault.

If you built an MCP server, claim the listing and help developers find accurate installation details. Verification is free during early access and gives users a clearer signal before they connect a tool to their work.

Claim your MCPVault listing if it is not indexed yet.