Claude Code MCP Setup: 7 .mcp.json Examples to Copy

Published 2026-10-23 · 6 min read · by AgentKit Co

MCP (Model Context Protocol) servers give Claude Code new tools: your issue tracker, a database, a browser, an internal API. You can add one with a single claude mcp add command, or write it into a .mcp.json file at the root of your repo so everyone on the team gets the same tools.

This guide gives you seven configs to copy, explains the three scopes (the part that confuses most people), and lists the fixes for servers that show a red ✘. Everything here was checked against Anthropic's MCP docs for Claude Code on 2026-10-23. Claude Code changes quickly, so re-check anything you rely on.

Where your MCP config lives

Two things trip people up here. First, "local" MCP servers are not stored in the project folder; they live in ~/.claude.json in your home directory. Second, if the same server name exists in more than one scope, Claude Code uses the whole entry from the highest one (local, then project, then user). Fields are not merged.

Pick a scope with --scope local, --scope project or --scope user on any claude mcp add command.

1. A remote HTTP server (one command)

Most hosted servers are remote HTTP. Notion's is a good first test:

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

Then run /mcp inside Claude Code to sign in. The same server as a shared .mcp.json entry:

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

streamable-http is accepted as an alias for http, so configs copied from a server's own docs usually work as-is.

2. GitHub with a token header

GitHub's remote server takes a personal access token as a header. Create a fine-grained token limited to the repos you want Claude to touch, then:

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

claude mcp add saves the config without checking the token, so a typo is accepted and only fails later. Run /mcp and look for a checkmark; a bad token shows ✘ and a 401 in the details.

3. A local stdio server with npx

Local servers run as a process on your machine. Everything after -- is the command that starts the server:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Keep --env away from the server name: if the name comes right after --env, the CLI reads it as another KEY=value pair and rejects it. Putting --transport stdio between them, as above, avoids that.

4. A read-only database

DBHub connects Claude to Postgres, MySQL and others. Use a read-only database user so nothing Claude runs can change data:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

Then ask plain questions like "Show me the schema for the orders table."

5. A team .mcp.json with secrets kept out of git

This is the pattern to commit. Each developer sets API_KEY in their own shell, and the file holds only the reference:

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

${VAR} expands an environment variable and ${VAR:-default} falls back to a default. Expansion works in command, args, env, url and headers.

One catch: Claude Code deliberately reads its own and your cloud credentials (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, NPM_TOKEN and similar) as empty in a remote server's url and headers, so a repo can't leak them. If you need one of those values, copy it into a variable with your own name.

6. Converting a Claude Desktop or Cursor config

Setup instructions written for other MCP clients usually give you an mcpServers block. Pass the inner object, not the wrapper, to claude mcp add-json:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

Two fixes before you paste: an entry with a url but no type needs "type": "http" (Claude Code treats a missing type as stdio, so it fails), and the server name may only use letters, numbers, hyphens and underscores.

7. Pre-approve one server's tools

MCP tools are named mcp__<server>__<tool>. To stop Claude asking every time it uses your GitHub server, add an allow rule to .claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__github__*"]
  }
}

The server part must be a literal name. A broad "mcp__*" allow rule is skipped and approves nothing, which is a safety feature, not a bug. (Our settings.json permissions guide covers allow, ask and deny in full.)

Commands you'll use every day

claude mcp list          # every server, with ✔ / ✘ status
claude mcp get notion    # details for one server
claude mcp remove notion # delete it (and its stored sign-in)

Inside a session, /mcp shows status, tool counts, sign-in and a toggle to disable a server without deleting it.

Why your MCP server won't connect

• ⏸ Pending approval. Servers from a project .mcp.json need your OK the first time. Run claude interactively in that folder and approve them. A freshly cloned repo can't approve its own servers through its committed settings until you trust the folder. To redo your choices, run claude mcp reset-project-choices.
• A url server that starts as stdio. Add the missing "type": "http".
• 401 with a ${VAR} header. Check that the variable is set in the shell you started Claude from, and that it isn't one of the credential names Claude Code reads as empty.
• "Leading or trailing whitespace" warning. A pasted token picked up a newline. Claude Code won't trim it for you, so edit the value.
• Two scopes, two definitions. Same name with different URLs gives a warning; keep one and remove the other with claude mcp remove <name> --scope <scope>.
• Reserved name. Names like workspace and computer-use belong to built-in servers and are skipped. Rename yours.
• A tool shows in /mcp but Claude can't call it. Full tool names over 128 characters are left out. Use a shorter server name.

FAQ

Should I commit .mcp.json? Yes, if the whole team should get the server. Keep every secret in ${VAR} references, never in the file.

Where do I put a server just for me? Use the default local scope for one project, or --scope user for all of them. Both go in ~/.claude.json, outside the repo.

Does Claude Code still support SSE servers? Yes. Add it with --transport sse, or with --transport http on Claude Code v2.1.265 or later, which tries HTTP first and switches to SSE when the server needs it.

Set up the rest of your agent config

MCP gives Claude tools; your instruction files tell it how to use them. The AI Coding Agent Config Kit has ready AGENTS.md, CLAUDE.md, Cursor rules and Copilot instructions for 12 stacks, and our CLAUDE.md examples and hooks examples cover the next two files most teams add.

Keep reading