Claude CodeBEGINNER
How to Connect an MCP Server to Claude Code (Step by Step)
Needs reviewLast verified August 12, 2026·5 min read
This guide walks through connecting a Model Context Protocol (MCP) server to Claude Code using the CLI. You will register a hosted server with the claude mcp add command, verify the connection with claude mcp list, use the server inside a session, and remove it when finished. It also covers what the connection status indicators mean, where the configuration is saved on disk, and the difference between local, user, and project scopes.
What MCP servers do for Claude Code
The Model Context Protocol (MCP) lets Claude Code use tools beyond its built-in set, such as searching an issue tracker, querying a database, or controlling a web browser. These tools come from MCP servers, which run on your machine or as hosted services.
This guide connects one server end to end with the Claude Code CLI. The example server is Anthropic's Claude Code documentation MCP server — a hosted server with full-text search over the Claude Code docs. It requires no authentication or special configuration, which makes it a good first server for testing the setup flow. The steps are the same for any server: add it, check the connection status, then use it in a session, with an optional cleanup step at the end.
Before you begin
Make sure you have:
- Claude Code installed and authenticated
- A terminal open in a project directory. Any directory works, including an empty one.
Step 1: Add the MCP server
Register the server with Claude Code. Run this in your terminal, not inside a claude session — you're configuring the server before starting a conversation:
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
Breaking down the command:
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 whatever name you pick to label the server's tools in Claude's output and to refer to the server in commands like 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. The local config part means the server is registered to you, in this project only — if you start Claude Code in a different project, this server isn't active there.
Step 2: Check the connection status
Confirm the server appears in your server list:
The server appears with a status indicator:
| Status | Meaning |
|---|
✔ Connected | Ready to use. This is what you should see for claude-code-docs |
! Connected · tools fetch failed | The server connected but couldn't list its tools. Run claude mcp get <name> for the error detail |
! Needs authentication | The server is reachable but needs a browser sign-in, or a token passed with --header |
✘ Failed to connect | Server didn't respond |
✘ Connection error | The connection attempt threw an error |
⏸ Pending approval (run claude to approve) | A project-scoped server you haven't approved yet |
Note that some legacy Windows consoles, such as the default console on Windows 10, don't support these Unicode glyphs and show √ and × in place of ✔ and ✘.
Step 3: Use the server in a session
Start a session and ask Claude to use the new server by name:
Use the claude-code-docs server to look up what MCP_TIMEOUT does
You don't normally need to name a server in your prompt, since Claude chooses relevant tools on its own. Naming it here guarantees the demonstration goes through the new server rather than another tool, such as web fetch, that could answer the same question.
The first time Claude calls the server, it asks for permission to use the new tool. Approve it to continue. The tool call in Claude's 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.
Step 4 (optional): Remove the server
When you're done experimenting, you can remove the server:
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.
There's a practical reason to clean up: 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.
Where servers are saved and how scopes work
The claude mcp add command 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.
A few additional notes from the documentation:
claude mcp add works the same in every shell, including PowerShell and Command Prompt.- Inside a
claude session, use the /mcp command to check and manage servers you've already added.
- The docs also describe other ways to add a server, such as running a local program on your machine instead of connecting to a URL, and editing
.mcp.json directly.
- You can also add MCP servers from other surfaces, including the desktop app, VS Code, and the web.
For more servers to connect, the documentation points to the Anthropic Directory, and the full MCP reference covers every way to connect and configure servers in Claude Code.
claudedetails.com is an independent publication and is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" is a trademark of Anthropic, PBC, used here for identification purposes only. Product details can change — always confirm specifics on Anthropic's own site before making decisions based on this post.
ClaudeDetails