3.2 MCP integration: stdio, SSE, .mcp.json, OAuth

Transports

MCP servers talk to Claude Code over one of two transports:

• stdio — Claude Code spawns the server as a subprocess and communicates via stdin/stdout. Simplest; ideal for local tools.
• SSE (Server-Sent Events over HTTP) — for remote servers you connect to over the network. The server exposes an HTTP endpoint; Claude Code streams events from it.

stdio is the common case: small local process, no network involved, no auth. SSE is for shared team servers or SaaS integrations that must live behind an API.

The .mcp.json config

Project-level MCP config lives at <repo>/.mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/notes"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgres://localhost/app"]
    },
    "notion": {
      "type": "sse",
      "url": "https://mcp.notion.com/sse",
      "auth": { "type": "oauth2" }
    }
  }
}

User-level: ~/.claude/mcp.json — same shape.

Auth

For stdio servers, auth is whatever the subprocess reads from env vars — you export the credential before launching Claude Code, or you set it in settings.json’s env block.

For SSE servers, MCP supports OAuth. The first time Claude Code connects, it opens a browser for the user to authorise; the returned token is cached in ~/.claude/tokens/. Subsequent sessions reuse the token until it expires; Claude Code refreshes silently.

For SSE without OAuth (rare, generally discouraged), a static bearer token can be configured:

{
  "type": "sse",
  "url": "https://internal.example.com/mcp",
  "auth": { "type": "bearer", "token": "$INTERNAL_MCP_TOKEN" }
}

Interpolation reads from the current process env.

Tool naming

Once a server is configured, its tools appear in Claude’s catalog with a mcp__<server>__<tool> prefix — e.g. mcp__notion__create_page. You can allow-list or deny-list these in permissions the same way you would built-ins.

Discovering what a server exposes

claude mcp list                     # servers configured
claude mcp tools filesystem         # tools exposed by "filesystem"
claude mcp tools notion --describe  # with descriptions

Useful when adding a new server — you know what tools you just gave Claude before it uses them.

Check your understanding

Quick check

—

You are configuring a Notion MCP server for your team. Where does the OAuth token that Claude Code obtains after the browser flow end up?

1. AInline in `.mcp.json` — commit it so teammates skip auth.
2. BCached in `~/.claude/tokens/` on each user's machine, refreshed silently on expiry.
3. CEmailed to you.
4. DNever persisted; auth happens every session.

Check answer→