Fabler Labs → Guides → Claude Code MCP

Claude Code MCP: how to add an MCP server

Free · no signup · verified against the docs · last updated July 2026

MCP — the Model Context Protocol — is how Claude Code reaches outside your codebase: to your GitHub, a Postgres database, Sentry, Notion, or a service you built. You add a server once and its tools and resources show up inside your session, so Claude can open issues, query a schema, or read a doc without you copy-pasting anything. This page is the practical version: the exact claude mcp add commands for each transport, the .mcp.json file you commit for your team, the config scopes, and the details that trip people up — env-var expansion and tool naming.

The fastest path: add a remote server

Most hosted services expose an HTTP endpoint. One command wires it up:

# Recommended for remote servers: --transport http
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Pass an auth header for a token-protected endpoint
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

If the server needs a login, it returns 401/403 on first use. Run /mcp inside Claude Code and complete the browser OAuth flow — tokens are then stored and refreshed for you. (SSE servers use --transport sse the same way, but the docs recommend HTTP; treat SSE as legacy.)

Add a local (stdio) server

A local server is just a command Claude Code launches as a subprocess and talks to over stdin/stdout. The key detail: everything after -- is the launch command, passed through untouched.

# Pattern:  claude mcp add [options]  --  [args...]
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

# A Postgres server over stdio
claude mcp add postgres \
  -- npx -y @bytebase/dbhub --dsn "postgresql://user:pass@localhost:5432/mydb"

The -- gotcha: the double dash separates Claude's own flags from the server's command. And when you use --env, put at least one other option (or the server name) between it and the command, or the CLI mistakes your server name for another KEY=value pair.

The .mcp.json file — share servers with your team

Everything above configures a server just for you. To commit servers into the repo so every teammate gets them, use project scope, which writes a .mcp.json at your repo root. You can create it with the CLI (claude mcp add --scope project …) or write it by hand. The top-level key is mcpServers:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_MCP_TOKEN}"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"],
      "env": {}
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp"
    }
  }
}

Because this file is committed, never hard-code secrets in it. Claude Code expands ${VAR} and ${VAR:-default} inside the command, args, env, url, and headers fields — so keys stay in your environment and the config stays shareable. If a referenced variable is unset and has no default, Claude Code refuses to parse the file rather than sending an empty value. Project servers also prompt each teammate for approval the first time; reset those choices with claude mcp reset-project-choices.

The three scopes

Where a server lives is controlled by --scope. Pick by who should see it:

When the same server name appears in more than one scope, the more specific one wins: local > project > user. The whole entry from the winning scope is used — fields aren't merged across scopes.

Managing servers

Four commands cover day-to-day life, plus the in-session panel:

claude mcp list            # list every configured server
claude mcp get github      # show one server's details
claude mcp remove github   # remove a server
claude mcp add-json db '{"type":"stdio","command":"…"}'   # add from raw JSON

Inside Claude Code, run the /mcp slash command to see each server's live status and tool count, complete OAuth logins, or clear stored authentication. Pending project servers show as awaiting approval until you accept them.

Using the tools and resources

Once a server is connected, its capabilities show up two ways:

• Tools are exposed to Claude with the naming convention mcp__<server>__<tool> — e.g. mcp__github__create_issue. That's the same name you'd use in a hook matcher or a permissions rule to allow or block a specific MCP tool.
• Resources a server exposes can be pulled into your prompt with an @ mention in the form @server:protocol://path. Typing @ autocompletes them alongside your files:

Can you analyze @github:issue://123 and suggest a fix?
Please review the API docs at @docs:file://api/authentication
Compare @postgres:schema://users with @docs:file://database/user-model

Servers can also expose prompts as slash commands, in the form /mcp__<server>__<prompt> — for example /mcp__github__list_prs.

Two things worth knowing before you scale up

• Output limits. MCP tool output warns at 10,000 tokens and is capped at 25,000 by default; raise it with the MAX_MCP_OUTPUT_TOKENS environment variable if a server legitimately returns more.
• Timeouts. Control startup and per-call timeouts with MCP_TIMEOUT and MCP_TOOL_TIMEOUT, or set a per-server "timeout" (milliseconds) in the config.

Rule of thumb: add the one or two servers you actually reach for — your issue tracker, your database — not everything you can find. Each server spends context and adds surface area; a focused set of MCP tools beats a crowded one. Pin server config in a committed .mcp.json so onboarding a teammate is one git pull.