How to connect Claude Code to an MCP server

Claude Code can use tools beyond its built-in set, such as searching an issue tracker, querying a database, or controlling a web browser. Those tools come from Model Context Protocol servers, which run on your machine or as hosted services. This walkthrough connects one hosted HTTP server with the Claude Code CLI: add it from the terminal, confirm the status, use it in a session, and choose local, user, or project scope.

Run the add command in your terminal, not inside a claude session. You are registering the server before the conversation starts. claude mcp add works the same in every shell, including PowerShell and Command Prompt.

Before you begin

Have Claude Code installed and authenticated, and open a terminal in a project directory. Any directory works, including an empty one.

The example is the hosted Claude Code documentation MCP server. It has full-text search over the Claude Code docs and does not require authentication or special configuration, so it works well as a first server to test the setup flow.

Add the HTTP server

Register the server:

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

• claude mcp add registers a server with Claude Code.
• --transport http means the server is hosted at a URL rather than run as a local process.
• claude-code-docs is a name you make up. Calling the same server docs would work identically. Claude Code uses the name you pick to label the server's tools and to refer to the server in commands such as claude mcp remove.
• https://code.claude.com/docs/mcp is the URL where the server is hosted.

The command prints a confirmation like Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config, followed by a File modified: line showing the configuration file it wrote. local config means the server is registered to you, in this project. If you start Claude Code in a different project, this server is not active there. Inside a session, use /mcp to check and manage servers you have already added.

Check the connection

Confirm the server appears in the list and check its status:

claude mcp list

For claude-code-docs, you should see ✔ Connected, which means it is ready to use. Other indicators on that list:

• ! Connected · tools fetch failed means the server connected but could not list its tools. Run claude mcp get <name> for the error detail.
• ! Needs authentication means the server is reachable but needs a browser sign-in, or a token passed with --header.
• ✘ Failed to connect means the server did not respond.
• ✘ Connection error means the connection attempt threw an error.
• A pending-approval status tells you to run claude to approve a project-scoped server you have not approved yet.
• ⊘ Disabled for this project (re-enable via /mcp) means the project's disabledMcpServers list turned the server off for this project.

Some legacy Windows consoles, such as the default console on Windows 10, do not support these glyphs and show √ and × in place of ✔ and ✘.

The Added confirmation means the entry was saved, not that the connection succeeded. claude mcp list is the check.

Use the server

Start a session:

claude

Ask Claude to use the new server by name:

Use the claude-code-docs server to look up what MCP_TIMEOUT does

You do not normally need to name a server, since Claude chooses relevant tools on its own. Naming it here keeps the demonstration on the new server rather than another tool, such as web fetch, that could answer the same question.

If Claude Code asks for permission the first time Claude calls the server, approve it. The tool call in the output is labeled with the server name, which is how you confirm the answer came from the MCP server rather than Claude's built-in knowledge.

Choose local, user, or project scope

claude mcp add writes the server's details to a configuration file. By default it registers the server at local scope: private to you, active only in the current project. Pass --scope user to register it once for all your projects, or --scope project to share it with teammates.

On Windows, ~/.claude.json resolves to %USERPROFILE%\.claude.json, typically C:\Users\YourName\.claude.json. If you have set CLAUDE_CONFIG_DIR, Claude Code reads .claude.json from inside that directory instead. Run claude mcp get claude-code-docs to see which scope holds a server's definition.

A server's scope is fixed when you add it, so changing scope means removing the entry and re-adding it. If the local entry from the first walkthrough is still present, remove it so the server has only one definition. Skip this if you already removed it:

claude mcp remove claude-code-docs --scope local

To make the server active in every project you open, still private to you:

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

To share it with your team, re-add it at project scope. That writes .mcp.json in the project root:

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

Commit .mcp.json to version control. Teammates who clone the repository and start Claude Code see a prompt to approve the server, then it connects for them too. The first time Claude Code sees a project-scoped server, it asks you to approve it so a repository you clone cannot launch processes on your machine without your consent. Approve the prompt, or run /mcp to approve later. Claude Code reads .mcp.json at session start, so start a new session after you change the file.

If /mcp shows that no MCP servers are configured, a local-scoped add may have been run from a different project. Local scope is tied to the project where you added the server: the repository root, or the exact directory if you were not in a git repository. Re-add it from the project you are in now, or add it with --scope user. Claude Code does not read paths such as ~/.claude/.mcp.json or ~/.claude/mcp.json.

Remove the server

Cleanup is optional:

claude mcp remove claude-code-docs

The command confirms with Removed MCP server "claude-code-docs" from local config and a File modified: line showing the file it updated. Each connected server takes some space in Claude's context window, because its tool names and server instructions load into every session. Removing servers you no longer use keeps that space free.

If the name exists at more than one scope, remove reports that it exists in multiple scopes. Pass --scope to choose which copy to delete, for example claude mcp remove claude-code-docs --scope local.

When the server needs a sign-in or a token

The docs server does not need authentication. Other hosted servers can. After you add one that uses browser sign-in, claude mcp list can show ! Needs authentication. Start a session, run /mcp, select the server, and choose Authenticate.

Servers that authenticate with a static token instead of OAuth take the token at add time with --header "Authorization: Bearer <token>" on the claude mcp add command. The quickstart states that flag and points to a GitHub example for a worked version, rather than printing the full command on this page. Use that worked example. Do not assemble the rest of the line from memory. A 401 or 403 from the page's HTTP reachability check means the server is up and you still need the browser sign-in or that token.

What to try next

From a project directory, add the docs server with the HTTP command and run claude mcp list until the status is ✔ Connected. Start claude and ask it to look up MCP_TIMEOUT through claude-code-docs. If the server should follow you across projects or ship with the repo, remove the local entry and add it again with --scope user or --scope project. For sign-in failures, startup timeouts, and servers that connect with no tools, use the troubleshooting section on the same Claude Code MCP quickstart.

Sources

• Connecting one MCP server with the Claude Code CLI