How to connect Claude Code to MCP servers

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. Those tools come from MCP servers that run on your machine or as hosted services. This walkthrough connects one server end to end with the Claude Code CLI.

Before you begin

You need Claude Code installed and authenticated, and a terminal open in a project directory. Any directory works, including an empty one. Run add commands in the terminal, not inside a claude session. Inside a session, /mcp checks and manages servers you have already added.

Add the hosted docs server

The Claude Code documentation MCP server is hosted, has full-text search over the docs, and needs no authentication — a clean first test.

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

claude mcp add registers a server. --transport http means it is hosted at a URL rather than run as a local process. claude-code-docs is a name you make up; Claude Code uses it to label tools and in commands such as claude mcp remove. The last argument is the hosted URL.

The command prints a confirmation like Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config, then a File modified: line. Local config means the server is registered to you, in this project only.

Confirm it appears and check status:

claude mcp list

For this server you should see ✔ Connected. Other statuses include ! Connected · tools fetch failed (run claude mcp get <name> for the error), ! Needs authentication, ✘ Failed to connect, ✘ Connection error, pending approval for a project-scoped server you have not approved yet, and disabled for this project via disabledMcpServers. Some legacy Windows consoles show √ and × in place of ✔ and ✘.

Use it in a session

claude

Then ask:

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

You do not normally need to name a server — Claude chooses relevant tools on its own. Naming it here keeps the demo on the new server rather than web fetch. Approve permission if asked. Tool calls in the output are labeled with the server name, which confirms the answer came from MCP.

Removing the server is optional. Each connected server takes space in Claude’s context window because tool names and server instructions load into every session:

claude mcp remove claude-code-docs

You should see Removed MCP server "claude-code-docs" from local config and a File modified: line.

Local, user, and project scope

By default, claude mcp add writes local scope: private to you, active only in the current project. Use --scope user for all your projects, or --scope project to share with teammates.

On Windows, ~/.claude.json resolves to %USERPROFILE%\.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 definition.

Scope is fixed at add time. To change it, remove and re-add. If the local entry is still there:

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

All your projects, still private to you:

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

Share with the team (writes .mcp.json in the project root; commit it):

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

Teammates who clone the repository and start Claude Code see a prompt to approve the server, then it connects for them. That prompt exists so a cloned repo cannot launch processes without consent. claude mcp add works the same in every shell, including PowerShell and Command Prompt.

You can also write .mcp.json by hand. Create it in the project root:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

HTTP entries use url. Stdio entries use command and args. Claude Code reads the file at session start. If you previously rejected a project-scoped server, run claude mcp reset-project-choices.

Local stdio: Playwright

A local stdio server is a program Claude Code starts as a subprocess. Playwright gives Claude a browser it can navigate, click, and read. 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 — local servers use the default stdio transport. Everything after -- is the start command. -y tells npx to install without prompting.

The Added line means the entry was saved, not that the process already runs. claude mcp list can show ✘ Failed to connect while npx downloads; wait and list again. Once connected:

Use playwright to open https://example.com and tell me the page title

A browser window opens. Tool calls are labeled playwright with the action, such as browser_navigate. Playwright drives whichever Chrome is already installed. To use another browser, append --browser with the browser name, for example --browser firefox, after @playwright/mcp@latest.

HTTP OAuth: Sentry

Hosted services such as Sentry, Linear, and Notion put MCP behind OAuth. Add the URL, then sign in in the browser. Sentry is the documented example:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

claude mcp list then shows ! Needs authentication. Start a session, run /mcp, select sentry, press Enter, and choose Authenticate. Approve Sentry’s sign-in page in the browser. Status then changes to connected. Ask something like What Sentry projects do I have access to? and look for sentry in the tool-call labels.

Servers that use a static token instead of OAuth take it at add time with --header "Authorization: Bearer <token>".

If a server does not connect, match the status from claude mcp list or /mcp. Local-scope adds are tied to the project directory where you ran them. Claude Code reads ~/.claude.json and <project>/.mcp.json only. For HTTP reachability, curl -I https://mcp.sentry.dev/mcp (use curl.exe in PowerShell). For Playwright, run npx -y @playwright/mcp@latest directly. If startup exceeds the default 30-second timeout, use MCP_TIMEOUT=60000 claude.

Try this next

From a project directory, run the docs-server add command, then claude mcp list until you see ✔ Connected. Start claude and ask it to look up MCP_TIMEOUT through claude-code-docs. When you want more servers, team scopes, or organization policy, continue on the official MCP quickstart.

Sources

• Claude Code MCP quickstart