◆ Sparround

Connecting an MCP server to Claude Code

A server is connected with claude mcp add and stored in one of three scopes:

  • `local` (the default) — just for you, in the current project. For personal and experimental servers.
  • `project` — in a .mcp.json file at the project root. Committed to the repo and shared with the team.
  • `user` — just for you, across all projects. For personal helper tools.

The important one for a team is project scope: the server configuration travels with the repo so each developer doesn't set it up separately.

json
{
  "mcpServers": {
    "crash-reporting": {
      "type": "http",
      "url": "https://mcp.example-crash-service.com/mcp",
      "headers": {
        "Authorization": "Bearer ${CRASH_SERVICE_TOKEN}"
      }
    },
    "android-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["./tools/mcp/android-server.js"],
      "env": {
        "ANDROID_SDK_ROOT": "${ANDROID_SDK_ROOT}"
      }
    }
  }
}

`.mcp.json` at the project root. Note: keys are **never written inline** — they come from environment variables via `${VAR}`. The `${VAR:-default}` form is supported too.

CommandWhat it does
`claude mcp add --transport http <name> <url>`Connects a remote server
`claude mcp add --scope project …`Writes the configuration to `.mcp.json` (for the team)
`claude mcp list`Lists connected servers
`claude mcp get <name>`Shows one server's details
`claude mcp remove <name>`Removes a server
`/mcp` (inside a session)Shows server status and OAuth login

Project-scoped servers require approval before first use. That is deliberate: when you clone a repo, its .mcp.json would otherwise start servers someone else configured. claude mcp reset-project-choices resets your approval decisions.

After connecting, verify in this order:

1. /mcp — does the server show as connected?

2. Ask something simple: "what tools does the crash-reporting server offer?"

3. A real task: "find the latest crash and explain it".

If tools don't appear, the usual causes are: the server didn't start (wrong path or command), authentication failed (the environment variable isn't set), or project scope approval wasn't given.

📚 Sources and documentation