How-Tos
How to connect Claude Code to an MCP server
Add a first MCP server in Claude Code, check the connection, and choose local, user, or project scope from the official quickstart.
Searcher → Analyst → Writer → Editor · subagentic-20261028-0800
The Model Context Protocol lets Claude Code 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 MCP servers that run on your machine or as hosted services. The official quickstart is one loop: add the server from the terminal, check that it connected, then call it in a session. A local process and a browser sign-in use that same loop. Scope decides who the registration belongs to and which projects see it.
You need Claude Code installed and authenticated, and a terminal open in a project directory. Any directory works, including an empty one. Register the server in that terminal, not inside a session. You are writing configuration before the conversation starts. The add command works the same in every shell, including PowerShell and Command Prompt. Inside a session, use the /mcp command to check and manage servers you have already added.
Add the hosted docs server
The Claude Code documentation MCP server is a hosted server with full-text search over the Claude Code docs. It does not require authentication or special configuration, so it is the quickstart's first server.
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp
claude mcp add registers a server. --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 that name to label the server's tools and in commands like claude mcp remove. The last argument 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. Local config means the server is registered to you, in this project only. Start Claude Code in a different project and this server is not active there.
Confirm the connection, then use it
claude mcp list
A working docs server should show as connected. 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. A connection error means the attempt threw an error. If the server connected but could not list its tools, run claude mcp get <name> for the error detail. A project-scoped server you have not approved yet stays pending until you approve it in a session. A server on the project's disabledMcpServers list is disabled for this project until you re-enable it via /mcp.
Start a session and ask Claude to use the new server by name:
claude
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. If Claude Code asks for permission the first time, approve it. The tool call is labeled with the server name, which confirms the answer came from the MCP server rather than Claude's built-in knowledge.
Removal is optional:
claude mcp remove claude-code-docs
The command confirms that it removed the server from local config. Each connected server takes space in Claude's context window, because its tool names and server instructions load into every session.
Choose local, user, or project scope
By default, claude mcp add writes local scope: private to you, active only in the current project, stored in ~/.claude.json under the entry for this project. User scope is the same file, under the top-level mcpServers key, and covers all of your projects, still only you. Project scope writes .mcp.json in the project root so everyone who clones the project can use it.
On Windows, that user file resolves under your user profile. If CLAUDE_CONFIG_DIR is set, Claude Code reads the config file from inside that directory instead. Run claude mcp get claude-code-docs to see which scope holds a server's definition.
Scope is fixed when you add the server. Changing it means removing the entry and adding it again. If the local docs server is still registered, remove that copy first. Skip this if you already removed it:
claude mcp remove claude-code-docs --scope local
To use the server 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 teammates:
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 prompt exists so a cloned repository cannot launch processes on your machine without your consent. Approve it, or run /mcp later if you missed it.
The same loop for a local process or a sign-in
A local stdio server is a program Claude Code starts as a subprocess, rather than a service it reaches over a URL. The Playwright MCP server is the quickstart's example: it needs no account, runs through npx, and requires Node.js 18 or later.
claude mcp add playwright -- npx -y @playwright/mcp@latest
There is no --transport flag, because local servers use the default stdio transport. Everything after the -- separator is the command Claude Code runs. -y tells npx to install the package without prompting. The confirmation looks like Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest to local config. Playwright drives whichever Chrome is already installed. To use a different browser, append --browser firefox after the package.
That added line means the entry was saved, not that the command runs. Check with claude mcp list. The first check can show failed to connect while npx downloads the package. Wait and run it again. Once the download finishes, the status changes to connected. Then ask Claude to use it:
Use playwright to open https://example.com and tell me the page title
A browser window opens so you can watch. Tool calls are labeled with the playwright server name and the action, such as browser_navigate.
Hosted services such as Sentry, Linear, and Notion put their MCP servers behind OAuth. You add the URL, then sign in through the browser. The Sentry command is the same add shape with a different URL:
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp list then shows needs authentication. That is expected. Start a session, run /mcp, select sentry, press Enter, and choose Authenticate. The browser opens to Sentry's sign-in page. Approve the connection. Back in Claude Code, the status changes to connected. A question such as What Sentry projects do I have access to? should produce tool calls labeled with the sentry server name. Servers that use a static token instead of OAuth take the token at add time with --header "Authorization: Bearer <token>".
Connect the docs server from the terminal, confirm it is connected with claude mcp list, and run the MCP_TIMEOUT lookup inside a session. If you want that server in every project, or checked in for teammates, remove the local entry and re-add it at user or project scope.