{ "type": "guide", "id": "add-mcp-servers-to-claude-code", "title": "Add MCP servers to Claude Code", "summary": "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.", "author": "Agentica Author", "tags": [ "mcp", "claude-code", "setup" ], "published": "2026-10-02", "last_verified": "2026-10-02", "difficulty": "beginner", "time_estimate": "10 min", "entries": [ "claude-code", "model-context-protocol", "github-mcp-server", "playwright-mcp", "notion-mcp" ], "links": { "html": "https://indexagentica.com/guides/add-mcp-servers-to-claude-code/", "markdown": "https://indexagentica.com/guides/add-mcp-servers-to-claude-code.md", "json": "https://indexagentica.com/api/longform/guides/add-mcp-servers-to-claude-code.json", "source": "https://github.com/Drudley/indexagentica/blob/main/content-long/guides/add-mcp-servers-to-claude-code.md" }, "status": "published", "prerequisites": [ "Claude Code installed and signed in", "Node.js 18+ for local servers started with npx", "A GitHub personal access token for the GitHub example" ], "entries_detail": [ { "id": "claude-code", "name": "Claude Code", "summary": "Anthropic's agentic coding tool that reads your codebase, edits files, runs commands and integrates with dev tools; available in terminal, IDE, desktop and browser.", "url": "https://indexagentica.com/entries/claude-code/", "json": "https://indexagentica.com/api/entries/claude-code.json" }, { "id": "model-context-protocol", "name": "Model Context Protocol (MCP)", "summary": "Open protocol that standardizes how AI applications connect to external tools, data sources and prompts via MCP servers.", "url": "https://indexagentica.com/entries/model-context-protocol/", "json": "https://indexagentica.com/api/entries/model-context-protocol.json" }, { "id": "github-mcp-server", "name": "GitHub MCP Server", "summary": "GitHub's official MCP server: lets agents read repos and code, manage issues and PRs, analyze code and monitor Actions workflows.", "url": "https://indexagentica.com/entries/github-mcp-server/", "json": "https://indexagentica.com/api/entries/github-mcp-server.json" }, { "id": "playwright-mcp", "name": "Playwright MCP", "summary": "Microsoft's MCP server for browser automation with Playwright, letting LLMs act on web pages via structured accessibility snapshots instead of screenshots.", "url": "https://indexagentica.com/entries/playwright-mcp/", "json": "https://indexagentica.com/api/entries/playwright-mcp.json" }, { "id": "notion-mcp", "name": "Notion MCP", "summary": "Notion's hosted remote MCP server that lets MCP clients search, read and write in your Notion workspace.", "url": "https://indexagentica.com/entries/notion-mcp/", "json": "https://indexagentica.com/api/entries/notion-mcp.json" } ], "related": [ { "type": "guide", "id": "connect-an-agent-to-a-remote-mcp-server", "title": "Connect an agent to a remote MCP server", "url": "https://indexagentica.com/guides/connect-an-agent-to-a-remote-mcp-server/", "json": "https://indexagentica.com/api/longform/guides/connect-an-agent-to-a-remote-mcp-server.json" }, { "type": "skill", "id": "connect-remote-mcp", "title": "Connect a remote MCP server", "url": "https://indexagentica.com/skills/connect-remote-mcp/", "json": "https://indexagentica.com/api/longform/skills/connect-remote-mcp.json" }, { "type": "stack", "id": "coding-agent-starter", "title": "Coding agent starter stack", "url": "https://indexagentica.com/stacks/coding-agent-starter/", "json": "https://indexagentica.com/api/longform/stacks/coding-agent-starter.json" }, { "type": "comparison", "id": "coding-agent-harnesses", "title": "Terminal coding agents compared", "url": "https://indexagentica.com/compare/coding-agent-harnesses/", "json": "https://indexagentica.com/api/longform/compare/coding-agent-harnesses.json" } ], "sources": [ { "title": "Claude Code docs, Connect Claude Code to tools via MCP", "url": "https://code.claude.com/docs/en/mcp", "accessed": "2026-10-02" }, { "title": "GitHub MCP server, Install in Claude applications", "url": "https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md", "accessed": "2026-10-02" }, { "title": "Playwright MCP README", "url": "https://github.com/microsoft/playwright-mcp", "accessed": "2026-10-02" } ], "front_matter": { "id": "add-mcp-servers-to-claude-code", "type": "guide", "title": "Add MCP servers to Claude Code", "summary": "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.", "description": "A short, verified walkthrough of claude mcp add for remote (HTTP) and local (stdio) servers, the local, project and user scopes, environment variable expansion in .mcp.json, OAuth sign-in with /mcp, and the status and troubleshooting commands. Examples use the hosted GitHub MCP server and Microsoft's Playwright MCP.", "author": "Agentica Author", "difficulty": "beginner", "time_estimate": "10 min", "prerequisites": [ "Claude Code installed and signed in", "Node.js 18+ for local servers started with npx", "A GitHub personal access token for the GitHub example" ], "tags": [ "mcp", "claude-code", "setup" ], "entries": [ "claude-code", "model-context-protocol", "github-mcp-server", "playwright-mcp", "notion-mcp" ], "sources": [ { "title": "Claude Code docs, Connect Claude Code to tools via MCP", "url": "https://code.claude.com/docs/en/mcp", "accessed": "2026-10-02" }, { "title": "GitHub MCP server, Install in Claude applications", "url": "https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md", "accessed": "2026-10-02" }, { "title": "Playwright MCP README", "url": "https://github.com/microsoft/playwright-mcp", "accessed": "2026-10-02" } ], "related": [ "connect-an-agent-to-a-remote-mcp-server", "connect-remote-mcp", "coding-agent-starter", "coding-agent-harnesses" ], "last_verified": "2026-10-02", "published": "2026-10-02" }, "markdown": "\n[Claude Code](https://indexagentica.com/entries/claude-code/) is an MCP client, so any [Model Context Protocol](https://indexagentica.com/entries/model-context-protocol/) server can give it new tools. There are two kinds:\n\n```mermaid\nflowchart LR\n CC[Claude Code] -- Streamable HTTP --> GH[GitHub MCP server, hosted]\n CC -- stdio --> PW[Playwright MCP, local process]\n```\n\n- **Remote servers** run somewhere else and are reached over HTTP. You register a URL.\n- **Local servers** run as a process on your machine, and Claude Code talks to them over stdin and stdout. You register a launch command.\n\n## 1. Add a remote server\n\nThe hosted [GitHub MCP server](https://indexagentica.com/entries/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:\n\n```bash\nclaude mcp add --transport http github https://api.githubcopilot.com/mcp \\\n --header \"Authorization: Bearer $GITHUB_PAT\"\n```\n\nServers that support OAuth need no header. Add them by URL, then sign in from inside a session with `/mcp` (or `claude mcp login `; add `--no-browser` over SSH):\n\n```bash\nclaude mcp add --transport http notion https://mcp.notion.com/mcp\n```\n\nUse `--transport http`. The older SSE transport is deprecated, and recent Claude Code versions fall back to it automatically when a server only speaks SSE.\n\n## 2. Add a local server\n\n[Playwright MCP](https://indexagentica.com/entries/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:\n\n```bash\nclaude mcp add playwright -- npx @playwright/mcp@latest\n```\n\nPass 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:\n\n```bash\nclaude mcp add --env API_KEY=your-key --transport stdio example -- npx -y @example/mcp-server\n```\n\n## 3. Pick a scope\n\nEvery `claude mcp add` takes `--scope` (or `-s`):\n\n| Scope | Stored in | Who gets it |\n|---|---|---|\n| `local` (default) | `~/.claude.json`, under the current project's path | Only you, only in this project |\n| `project` | `.mcp.json` at the repository root | Everyone who clones the repo |\n| `user` | `~/.claude.json` | Only you, in every project |\n\nOlder 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`.\n\n## 4. Keep secrets out of shared config\n\nA 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`:\n\n```json\n{\n \"mcpServers\": {\n \"github\": {\n \"type\": \"http\",\n \"url\": \"https://api.githubcopilot.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${GITHUB_PAT}\"\n }\n }\n }\n}\n```\n\nIn JSON, always set `\"type\"`. A `url` without a type is an error, and `streamable-http` is accepted as an alias for `http`.\n\nProject-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`.\n\n## 5. Check that it worked\n\n| Command | What it does |\n|---|---|\n| `claude mcp list` | Lists servers with a status such as `✔ Connected`, `! Needs authentication` or `✘ Failed to connect` |\n| `claude mcp get ` | Shows one server's configuration and, on failure, an `Issue:` line with the HTTP status or error |\n| `/mcp` (inside a session) | Shows status and handles OAuth sign-in |\n| `claude mcp remove ` | Removes a server |\n\nTwo 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).\n\nFor 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](https://indexagentica.com/guides/connect-an-agent-to-a-remote-mcp-server/).\n", "raw": "---\nid: add-mcp-servers-to-claude-code\ntype: guide\ntitle: Add MCP servers to Claude Code\nsummary: 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.\ndescription: \"A short, verified walkthrough of claude mcp add for remote (HTTP) and local (stdio) servers, the local, project and user scopes, environment variable expansion in .mcp.json, OAuth sign-in with /mcp, and the status and troubleshooting commands. Examples use the hosted GitHub MCP server and Microsoft's Playwright MCP.\"\nauthor: Agentica Author\ndifficulty: beginner\ntime_estimate: 10 min\nprerequisites:\n - Claude Code installed and signed in\n - Node.js 18+ for local servers started with npx\n - A GitHub personal access token for the GitHub example\ntags: [mcp, claude-code, setup]\nentries: [claude-code, model-context-protocol, github-mcp-server, playwright-mcp, notion-mcp]\nsources:\n - title: Claude Code docs, Connect Claude Code to tools via MCP\n url: https://code.claude.com/docs/en/mcp\n accessed: 2026-10-02\n - title: GitHub MCP server, Install in Claude applications\n url: https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md\n accessed: 2026-10-02\n - title: Playwright MCP README\n url: https://github.com/microsoft/playwright-mcp\n accessed: 2026-10-02\nrelated: [connect-an-agent-to-a-remote-mcp-server, connect-remote-mcp, coding-agent-starter, coding-agent-harnesses]\nlast_verified: 2026-10-02\npublished: 2026-10-02\n---\n\n[Claude Code](https://indexagentica.com/entries/claude-code/) is an MCP client, so any [Model Context Protocol](https://indexagentica.com/entries/model-context-protocol/) server can give it new tools. There are two kinds:\n\n```mermaid\nflowchart LR\n CC[Claude Code] -- Streamable HTTP --> GH[GitHub MCP server, hosted]\n CC -- stdio --> PW[Playwright MCP, local process]\n```\n\n- **Remote servers** run somewhere else and are reached over HTTP. You register a URL.\n- **Local servers** run as a process on your machine, and Claude Code talks to them over stdin and stdout. You register a launch command.\n\n## 1. Add a remote server\n\nThe hosted [GitHub MCP server](https://indexagentica.com/entries/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:\n\n```bash\nclaude mcp add --transport http github https://api.githubcopilot.com/mcp \\\n --header \"Authorization: Bearer $GITHUB_PAT\"\n```\n\nServers that support OAuth need no header. Add them by URL, then sign in from inside a session with `/mcp` (or `claude mcp login `; add `--no-browser` over SSH):\n\n```bash\nclaude mcp add --transport http notion https://mcp.notion.com/mcp\n```\n\nUse `--transport http`. The older SSE transport is deprecated, and recent Claude Code versions fall back to it automatically when a server only speaks SSE.\n\n## 2. Add a local server\n\n[Playwright MCP](https://indexagentica.com/entries/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:\n\n```bash\nclaude mcp add playwright -- npx @playwright/mcp@latest\n```\n\nPass 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:\n\n```bash\nclaude mcp add --env API_KEY=your-key --transport stdio example -- npx -y @example/mcp-server\n```\n\n## 3. Pick a scope\n\nEvery `claude mcp add` takes `--scope` (or `-s`):\n\n| Scope | Stored in | Who gets it |\n|---|---|---|\n| `local` (default) | `~/.claude.json`, under the current project's path | Only you, only in this project |\n| `project` | `.mcp.json` at the repository root | Everyone who clones the repo |\n| `user` | `~/.claude.json` | Only you, in every project |\n\nOlder 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`.\n\n## 4. Keep secrets out of shared config\n\nA 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`:\n\n```json\n{\n \"mcpServers\": {\n \"github\": {\n \"type\": \"http\",\n \"url\": \"https://api.githubcopilot.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer ${GITHUB_PAT}\"\n }\n }\n }\n}\n```\n\nIn JSON, always set `\"type\"`. A `url` without a type is an error, and `streamable-http` is accepted as an alias for `http`.\n\nProject-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`.\n\n## 5. Check that it worked\n\n| Command | What it does |\n|---|---|\n| `claude mcp list` | Lists servers with a status such as `✔ Connected`, `! Needs authentication` or `✘ Failed to connect` |\n| `claude mcp get ` | Shows one server's configuration and, on failure, an `Issue:` line with the HTTP status or error |\n| `/mcp` (inside a session) | Shows status and handles OAuth sign-in |\n| `claude mcp remove ` | Removes a server |\n\nTwo 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).\n\nFor 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](https://indexagentica.com/guides/connect-an-agent-to-a-remote-mcp-server/).\n", "html": "

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

\n
flowchart LR\n  CC[Claude Code] -- Streamable HTTP --> GH[GitHub MCP server, hosted]\n  CC -- stdio --> PW[Playwright MCP, local process]
Mermaid diagram (source shown; this site uses no JavaScript)
\n
  • Remote servers run somewhere else and are reached over HTTP. You register a URL.
  • Local servers run as a process on your machine, and Claude Code talks to them over stdin and stdout. You register a launch command.
\n

1. Add a remote server

\n

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:

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

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):

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

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.

\n

2. Add a local server

\n

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:

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

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:

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

3. Pick a scope

\n

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

\n
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
\n

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.

\n

4. Keep secrets out of shared config

\n

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:

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

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

\n

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.

\n

5. Check that it worked

\n
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
\n

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).

\n

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.

" }