Index Agentica

Add MCP servers to Claude Code

Connect Claude Code to remote and local MCP servers from the command line, choose the right scope, keep tokens out of shared config, and check that each server connected, using GitHub and Playwright as examples.

Type
Guide
Author
Agentica Author
Published
Last verified
Difficulty
beginner
Time
10 min

Prerequisites

Claude Code is an MCP client, so any Model Context Protocol server can give it new tools. There are two kinds:

flowchart LR
  CC[Claude Code] -- Streamable HTTP --> GH[GitHub MCP server, hosted]
  CC -- stdio --> PW[Playwright MCP, local process]
Mermaid diagram (source shown; this site uses no JavaScript)

1. Add a remote server

The hosted GitHub MCP server lives at https://api.githubcopilot.com/mcp. With Claude Code, GitHub's own install guide authenticates it with a personal access token sent as a header:

claude mcp add --transport http github https://api.githubcopilot.com/mcp \
  --header "Authorization: Bearer $GITHUB_PAT"

Servers that support OAuth need no header. Add them by URL, then sign in from inside a session with /mcp (or claude mcp login <name>; add --no-browser over SSH):

claude mcp add --transport http notion https://mcp.notion.com/mcp

Use --transport http. The older SSE transport is deprecated, and recent Claude Code versions fall back to it automatically when a server only speaks SSE.

2. Add a local server

Playwright MCP runs on your machine through npx. Put the launch command after --, so flags such as -y go to the server command instead of being read as Claude Code options:

claude mcp add playwright -- npx @playwright/mcp@latest

Pass environment variables with --env (or -e). Put another option, such as --transport stdio, between the last --env pair and the server name; otherwise the CLI reads the name as one more KEY=value pair and rejects it:

claude mcp add --env API_KEY=your-key --transport stdio example -- npx -y @example/mcp-server

3. Pick a scope

Every claude mcp add takes --scope (or -s):

ScopeStored inWho gets it
local (default)~/.claude.json, under the current project's pathOnly you, only in this project
project.mcp.json at the repository rootEveryone who clones the repo
user~/.claude.jsonOnly you, in every project

Older guides call these project and global; GitHub's install guide notes that local used to be called project and user used to be called global.

4. Keep secrets out of shared config

A header passed on the command line is saved in the config file. For a project-scoped server that would put your token in .mcp.json, which gets committed. Instead, reference an environment variable; Claude Code expands ${VAR} and ${VAR:-default} in command, args, env, url and headers:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    }
  }
}

In JSON, always set "type". A url without a type is an error, and streamable-http is accepted as an alias for http.

Project-scoped servers ask for approval the first time you open the project interactively. They load without asking in claude -p runs, Agent SDK sessions and cloud sessions, so review .mcp.json in any repository before you run Claude Code on it unattended, or start with --strict-mcp-config and pass only the servers you want with --mcp-config.

5. Check that it worked

CommandWhat it does
claude mcp listLists servers with a status such as ✔ Connected, ! Needs authentication or ✘ Failed to connect
claude mcp get <name>Shows one server's configuration and, on failure, an Issue: line with the HTTP status or error
/mcp (inside a session)Shows status and handles OAuth sign-in
claude mcp remove <name>Removes a server

Two limits are worth knowing. Server startup times out after a default you can change with MCP_TIMEOUT (in milliseconds), and Claude Code warns when one tool result exceeds 10,000 tokens and cuts it off at 25,000 by default (MAX_MCP_OUTPUT_TOKENS raises the cap).

For connecting other clients (Codex, Cursor, Gemini CLI, VS Code) and for how remote MCP authorization works under the hood, see Connect an agent to a remote MCP server.

Directory entries in this guide

Related

Sources

Machine-readable