MCP servers in Claude Code: connect GitHub, databases and your own APIs

You need an MCP server in Claude Code when the built-in tools aren't enough: reading tickets from a tracker, querying a database, opening a pull request. The Model Context Protocol is an open standard for connecting such tools. Below are the claude mcp commands, the configuration scopes, two working examples, and how MCP affects token usage. Commands and keys were checked against the official Claude Code MCP page.

What MCP is

MCP (Model Context Protocol) defines how an AI application talks to external services. An MCP server exposes tools, resources and prompts, and Claude Code acts as the client. The agent calls connected tools the same way it calls built-ins like Read or Bash. Their names look like mcp__<server>__<tool>.

Transports:

• HTTP — a remote server at a URL. The docs recommend it for cloud services, and it supports OAuth;
• stdio — a local process on your machine (an npx package or your own script);
• SSE — deprecated; use HTTP where you can;
• WebSocket — configured only through JSON ("type": "ws").

File access and the terminal are built-in Claude Code tools, not MCP servers. You don't need to connect anything for them.

Adding an MCP server

A remote HTTP server:

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

With an authorization header:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

A local stdio server:

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

Everything after -- is the command that starts the server. Without the separator, Claude Code tries to parse the server's flags as its own.

Management:

claude mcp list
claude mcp get notion
claude mcp remove notion

Inside a session, /mcp shows server status (connected, failed, needs authentication), runs the OAuth sign-in, and lets you switch a server off without deleting its configuration.

Scopes: local, project, user

The --scope flag decides where the entry is stored:

MCP servers are not stored in ~/.claude/settings.json. A project .mcp.json looks like this:

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

.mcp.json supports ${VAR} and ${VAR:-default} expansion in command, args, env, url and headers, so secrets stay in the environment instead of the repo. An entry with a url must have a type; otherwise Claude Code treats it as a stdio server and skips it.

An important security detail: Claude Code's own credentials, including ANTHROPIC_AUTH_TOKEN, expand to empty in the url and headers of remote servers. Your Zukko key cannot leak to a third-party MCP server by accident. If a server needs a token, put it in a variable with a name of your own.

In an interactive session Claude Code asks for approval before using servers from .mcp.json. In claude -p mode there is no prompt, and project servers connect right away. Keep that in mind when you run it on someone else's repository.

Example: GitHub

The official example is GitHub's remote server with a fine-grained token:

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

Give the token access only to the repositories you need. Check the status with /mcp, then just ask in plain language: "Review PR #456 and suggest improvements", "Create an issue for the bug we just found". You don't need any special tool-call syntax in the prompt; the agent picks the tool itself.

Example: PostgreSQL

For databases, the docs use the DBHub server:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@localhost:5432/analytics"

Use a read-only database user so the agent's queries cannot modify data.

Your own MCP server

For your own API, the easiest route is an official MCP SDK (available for Python and TypeScript). You register functions with descriptions as tools, and the library implements the protocol. Connect the finished server over stdio:

claude mcp add --transport stdio my-api -- python /path/to/server.py

The SDK API differs between versions, so write the server code from the SDK docs at modelcontextprotocol.io. Don't hand-roll JSON-RPC: the server has to handle initialization and capability negotiation correctly.

MCP and token spend through Zukko

Claude Code connects to Zukko like this:

export ANTHROPIC_BASE_URL=https://api.zukko.pro
export ANTHROPIC_AUTH_TOKEN=fetch_your_key
export ANTHROPIC_MODEL=claude-sonnet-5

No /v1 in the base URL. More in the Claude Code guide↗.

One detail from the docs: when ANTHROPIC_BASE_URL points to a non-first-party host, MCP tool search is off by default. Every tool definition from every connected server then loads upfront and goes into the context with every request. In practice:

• keep only the servers you need connected and switch the rest off in /mcp;
• tool results go into the context too. Claude Code warns when a result exceeds 10,000 tokens and caps it at 25,000 by default (change the cap with MAX_MCP_OUTPUT_TOKENS). Ask the agent to fetch narrowly: a filtered SQL query, a specific PR, not everything.

A worked estimate. Say tool definitions take 15,000 tokens and the session makes 100 model requests: 15,000 × 100 = 1,500,000 tokens, or 1.5 × $0.3 = $0.45 on claude-sonnet-5 (input $0.3 per 1M). A caveat about caching: vendors charge about 10% of the input price for prompt-cache reads, while Zukko bills cached tokens at the normal input price. For repeated blocks like these, the real gap versus official pricing is smaller than a straight price comparison suggests. For the current model list, call GET https://api.zukko.pro/v1/models or open the Models page in your dashboard.

Create a key in your Zukko dashboard↗, where you can also set a daily limit and the list of allowed models.

FAQ

Where does Claude Code store MCP settings?

local and user servers live in ~/.claude.json; project servers live in .mcp.json at the project root.

What if a server takes a long time to start?

Set the startup timeout in milliseconds with MCP_TIMEOUT, for example MCP_TIMEOUT=10000 claude. /mcp shows the status and the connection error.

Can I connect several servers at once?

Yes. The docs set no fixed cap on servers or tools; the practical limit is context: more tools means more tokens spent on their definitions.

Do MCP servers work in non-interactive mode?

Yes. You can pass servers with --mcp-config. You can't complete an OAuth sign-in in -p mode, though, so authorize beforehand in an interactive session with /mcp.