All insights

Coding agents

Claude Code: How to Add an MCP Server

Add an MCP server to Claude Code with a documented command, choose local, project, or user scope, and check its connection. Learn where project configuration belongs and what to check if a server is missing.

Illustration for Claude code add mcp server

Add an MCP server to Claude Code

For a first test, open a terminal and change to the project directory where you want the server available. Run the command in your terminal, not inside a Claude Code session. This example uses the default local scope, which is private to you and active only in the current project:

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

claude-code-docs is the server name in this example. The command registers the HTTP endpoint; registration alone does not confirm that Claude Code has connected. The endpoint’s authentication requirements have not been confirmed here. Check the official quickstart for any endpoint-specific requirements.

To connect a different server, use its documented endpoint, transport, and authentication instructions. Review whether you trust a server before connecting it, particularly if it can fetch external content.

Choose a scope

Choose a scope based on where you want the server available:

  • Local: Private to you and active only in the current project. This is the default when you omit a scope flag.
  • User: Available to you across projects. Add --scope user to the command.
  • Project: Intended to be shared with teammates. Add --scope project to the command.

For the local example, make sure you are in the intended project directory before running it. For project scope, run the command from the project whose configuration you want to update:

claude mcp add --transport http --scope project claude-code-docs https://code.claude.com/docs/mcp

Project configuration belongs in .mcp.json at the project root, alongside the .claude directory—not in .claude/.mcp.json. A Claude Code resolution comment on issue #5037 says .claude/.mcp.json is not read as MCP configuration and identifies root-level .mcp.json as the project-scope file. The comment reports checking this behavior on Claude Code 2.1.235 on Linux; that report is not a test of every version, operating system, or editor.

A project server may require approval. Review any project-server approval prompt and approve the server only if you trust it. For the current approval instructions, see the MCP documentation. Registration or appearing in a list is not, by itself, proof that the server has been approved.

Check the connection and troubleshoot

After adding the server, check its status by name:

claude mcp get claude-code-docs

The MCP reference documents this as a check that Claude Code connected. The available instructions here do not confirm a separate step for verifying that this example’s tools are available in a session, so treat the connection check as confirmation of connection—not proof that a tool call will work.

If a project server is missing or not connected:

  1. Confirm you ran the command from the intended project directory and, for project scope, that the file is .mcp.json at the project root—not inside .claude/.
  2. Check the JSON syntax and that the top-level server map is named mcpServers.
  3. Review any approval prompt and check the server provider’s endpoint and authentication instructions.
  4. Recheck status with claude mcp get <name>.

In the resolution comment on Claude Code issue #5037, a Claude Code contributor reported that on Claude Code 2.1.235 on Linux, claude mcp list reported parse errors for examples such as a trailing comma or using servers instead of mcpServers. Treat those as version- and platform-conditioned examples, not a guarantee of identical diagnostics in every client. The issue was separately closed as completed by a maintainer.

MCP setup is separate from production model API setup

claude mcp add registers an MCP server for Claude Code to connect to; it is not a model-selection command. MCP server setup does not, by itself, configure a production model API. Handle any credentials required by the MCP server according to that server’s instructions, separately from your application’s model/API configuration.

Sources

Connect to MCP servers — Claude Code Docs

Connect Claude Code to tools via MCP — Claude Code Docs

MCP servers in .claude/.mcp.json not loading properly — Claude Code issue #5037

Contact us