Claude Code MCP Servers: .mcp.json Setup Guide with Examples

Published Oct 15, 2026 · 10 min read

Short answer: to add an MCP server to Claude Code, either run claude mcp add or create a .mcp.json file in your project root with an mcpServers object. Remote servers use "type": "http" and a url; local servers use "type": "stdio" with a command and args. Start a new session, approve the server when prompted, and check it with /mcp.

MCP (Model Context Protocol) servers give Claude Code new tools: query your Postgres database, drive a real browser with Playwright, read GitHub issues, or pull errors from Sentry. This guide covers the three config scopes, the exact JSON format, safe secret handling, permissions, and five configs you can copy.

The three MCP scopes

Use project scope for tools the whole team needs (it's configuration as code, reviewed in PRs). Use user scope for personal tools such as a docs server you like. Use local for experiments.

Adding a server from the CLI

# Remote HTTP server, shared with the team via .mcp.json
claude mcp add --transport http --scope project github https://api.githubcopilot.com/mcp/

# Local stdio server (everything after -- is the command)
claude mcp add --scope project playwright -- npx -y @playwright/mcp@latest

# Check what's configured and connected
claude mcp list
claude mcp get playwright

Each claude mcp add prints an "Added" line on success. Inside a session, /mcp shows connection status and lets you authenticate servers that use OAuth.

The .mcp.json format

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

• HTTP servers need type and url, plus optional headers. streamable-http is accepted as an alias for http.
• stdio servers need command and args, plus optional env.
• Always set type when you set url. An entry with a url but no type is read as stdio and skipped with an error.

Keep secrets out of .mcp.json

Because .mcp.json is committed, never paste tokens into it. Claude Code expands environment variables in command, args, env, url and headers:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${INTERNAL_API_TOKEN}" }
    }
  }
}

${VAR} is replaced with the variable's value and ${VAR:-default} falls back to the default. Each teammate exports their own token in their shell; the file in git stays clean. Pair this with a hook that blocks edits to .env so Claude can't leak or overwrite secrets either.

5 MCP configs worth copying

1. Playwright: let Claude test in a real browser

{
  "mcpServers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Ask "open localhost:3000, sign up with a test email and tell me what breaks". Claude clicks through the flow and reports back.

2. GitHub: issues and PRs without leaving the terminal

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

Use a fine-grained token scoped to the repos you need, with read-only permissions to start.

3. Postgres: read-only database access

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL_READONLY}"]
    }
  }
}

Point it at a read-only role or a staging replica. Never give an agent write access to production data.

4. Filesystem: a folder outside the repo

{
  "mcpServers": {
    "design-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}/work/design-docs"]
    }
  }
}

5. Sentry: debug from real production errors

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    }
  }
}

Run /mcp to complete the OAuth login, then ask "what's the top unresolved error this week and where in our code does it come from?".

Permissions: allow only the MCP tools you need

MCP tools are named mcp__<server>__<tool>. You can pre-approve or deny them in .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__playwright__*",
      "mcp__github__get_issue",
      "mcp__github__list_pull_requests"
    ],
    "deny": [
      "mcp__github__merge_pull_request"
    ]
  }
}

You can also give a subagent access to specific MCP tools only, for example a QA subagent that gets Playwright but not GitHub.

Approval and troubleshooting

• Project servers need approval. The first time Claude Code sees a server in .mcp.json it asks before starting it, so a cloned repo can't launch processes on your machine silently. Until approved, claude mcp list shows it as pending. claude mcp reset-project-choices clears earlier decisions.
• Server doesn't appear? .mcp.json is read at session start. Restart the session after editing it.
• "has a url but no type": add "type": "http".
• stdio server exits immediately? Run the exact command and args in your terminal to see the real error, which is often a missing env var or Node version.
• Too many tools? Every server adds tool definitions to context. Keep only the servers a project needs in its .mcp.json, and put personal extras in user scope.

A safe rollout plan for a team

1. Start in local scope. Try a server with claude mcp add (no --scope) for a few days and confirm it actually saves time.
2. Write down what it may touch. For each server, note the data it can read and the actions it can take. If a tool can delete, merge or write, deny it in permissions.deny until someone asks for it.
3. Promote to project scope in a PR. Move the entry into .mcp.json with env-var placeholders and document the variables in your README or CLAUDE.md so teammates know what to export.
4. Use least-privilege credentials. Read-only database roles, fine-grained GitHub tokens, staging rather than production.
5. Review it like code. Changes to .mcp.json and .claude/settings.json change what an agent can do on everyone's machine, so require a reviewer for them.

This sounds like process for its own sake, but MCP is where an agent stops editing text files and starts acting on real systems. A ten-minute review of a JSON file is cheap insurance against an agent with production write access.

Where MCP fits with the rest of your setup

MCP gives Claude new capabilities. Your CLAUDE.md tells it the project's facts, skills and slash commands package repeatable procedures, subagents give roles their own tools, and hooks enforce the rules that must never be broken. The more tools you connect, the more those guardrails matter.