AI Coding Guide

Adding MCP servers to Claude Code: claude mcp add versus .mcp.json

Claude Code Published:

Add and manage MCP servers in Claude Code: claude mcp add for stdio and HTTP servers, the local / project / user scopes, sharing via .mcp.json, authentication and troubleshooting.

Verified on Sep 7, 2026 These tools change quickly. Please also check the latest official documentation.
#Claude Code#MCP#configuration#integrations
Contents
  1. The add command
    1. stdio servers (a local process)
    2. HTTP / SSE servers (remote)
  2. Scopes: where the configuration lives
  3. Checking the connection
  4. Allowing tools to run without prompts
  5. Which server first?
  6. Summary

MCP (Model Context Protocol) is the common standard for connecting external tools and data sources to AI agents. Add an MCP server to Claude Code and it can drive a browser, read GitHub issues or query a database on its own initiative.

This article covers the claude mcp add command and the scopes that decide whether a server is yours only, shared with the whole team on this project, or available in all your projects.

KEY POINT

What you will learn

  • The basic form of claude mcp add and the difference between stdio and HTTP servers
  • The local / project / user scopes and where each is stored
  • Connection checks, authentication and permission rules

The add command

stdio servers (a local process)

Most MCP servers ship as npm packages and start with npx.

claude mcp add <name> -- <command> [args...]

For example, the Playwright server for browser automation:

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

Everything after -- is the command that starts the server. Pass environment variables with -e:

claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx -- npx -y @modelcontextprotocol/server-github

HTTP / SSE servers (remote)

Connect to a hosted server with --transport http:

claude mcp add --transport http <name> <URL>

Servers that require authentication can be signed into from the /mcp command during a session (OAuth in the browser).

用語解説

stdio versus HTTP: stdio starts a local server process and talks to it over standard input and output. HTTP connects to a server that is already running at a URL. Tools that touch local files or a browser are usually stdio; official servers offered by SaaS products are usually HTTP.

Scopes: where the configuration lives

The --scope option decides where the server is saved and who sees it.

ScopeStored inVisible toGood for
local (default)~/.claude.json (per-project entry)You, this project onlyTrying things out, servers with credentials
project.mcp.json at the repository rootThe whole team (committed)Tools the project relies on
user~/.claude.jsonYou, all projectsGeneral-purpose tools
# Share with the team
claude mcp add --scope project playwright -- npx @playwright/mcp@latest

# Available in all your projects
claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp

Adding with project scope produces a .mcp.json like this. You can also write it by hand.

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

.mcp.json expands ${NAME} from your environment. Never write the token itself; let each developer provide it through their shell.

Do not put tokens in .mcp.json

.mcp.json is committed to Git. A token written directly into env is visible to everyone who can read the repository. Reference an environment variable with ${VAR}, or use the local scope.

Checking the connection

claude mcp list        # servers and their status
claude mcp get github  # one server's configuration
claude mcp remove github

During a session, /mcp shows each server's status, the tools it exposes and whether it needs authentication. If a server shows as failed, the quickest diagnosis is to start it by hand and read the error:

npx @playwright/mcp@latest   # run it standalone

Allowing tools to run without prompts

MCP tools are confirmed before running, like any other tool. Frequently used ones can be allowed in settings.json:

{
  "permissions": {
    "allow": [
      "mcp__playwright",
      "mcp__github__get_issue",
      "mcp__github__list_pull_requests"
    ],
    "ask": [
      "mcp__github__create_pull_request"
    ]
  }
}

mcp__server covers every tool of a server; mcp__server__tool targets one tool. Keep write operations under ask. The full permission syntax is in Claude Code permissions in settings.json.

Which server first?

Start with the one that provides information Claude cannot otherwise see in your daily work: the real browser (Playwright), current library documentation (Context7), or issues and pull requests (GitHub). Those three give the most noticeable improvement.

Summary

  • claude mcp add name -- command adds a stdio server; --transport http adds a remote one
  • Scopes: local (you only), project (.mcp.json, shared), user (all your projects)
  • Reference tokens as ${VAR}; never write them into .mcp.json
  • Check with /mcp and claude mcp list, then decide what to auto-allow in permissions

FAQ

Where is the MCP server configuration stored?
It depends on the scope. local and user servers are stored in ~/.claude.json; project servers go in .mcp.json at the repository root.
How do I check that a server is connected?
Run /mcp during a session to see each server's status and the tools it provides. From the shell, claude mcp list shows the same.
Can MCP tools run without confirmation?
Yes. Add mcp__server__tool (or mcp__server for the whole server) to permissions.allow in settings.json.

Primary sources

This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.

Related articles