MCP — Model Context Protocol

# HTTP — recommended
claude mcp add --transport http notion \
  https://mcp.notion.com/mcp
# ...with an auth header
claude mcp add --transport http secure-api \
  https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# stdio — locally running servers
claude mcp add --transport stdio myserver \
  --env KEY=value -- npx @myorg/mcp-server

# SSE — deprecated, still supported
claude mcp add --transport sse legacy \
  https://example.com/sse

• HTTP is the recommended transport — remote servers, header-based or OAuth auth
• stdio spawns a local process; since v2.1.139 every stdio server gets CLAUDE_PROJECT_DIR in its environment, and ${CLAUDE_PROJECT_DIR} substitutes into command, args, and env before launch
• SSE is deprecated in favor of http
• Native Windows (not WSL): wrap npx as cmd /c npx -y @some/package

claude mcp add --transport http github \
  https://api.github.com/mcp
claude mcp list          # all servers
claude mcp get github    # one server's details
claude mcp remove github
claude mcp reset-project-choices
                         # redo .mcp.json approvals
claude mcp add-from-claude-desktop
                         # import Desktop config

/mcp inside a session

• Lists connected servers, triggers OAuth flows, inspects connection state
• v2.1.121+: initial connection retries up to 3× on transient errors
• v2.1.128+: shows each server's tool count and visually flags servers reporting 0 tools — misconfiguration stands out at a glance

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    },
    "local-server": {
      "command": "${MCP_BIN_PATH:-npx}",
      "env": {
        "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
      }
    }
  }
}

• ${VAR} — uses the environment variable, errors if not set
• ${VAR:-default} — falls back to the default if unset
• Expansion works in five fields: command, args, env, url, headers
• Export the real values once in ~/.bashrc / ~/.zshrc: GITHUB_TOKEN, DATABASE_URL, SLACK_TOKEN

// .mcp.json (project root)
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

> /mcp__github__get_pr 456
Title: Add dark mode support
Author: @alice · Status: OPEN
Reviewers: @bob, @charlie

Or skip the file: claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github after exporting the token.

Tool search — definitions on demand

Requires Sonnet 4+ or Opus 4+ — Haiku models are not supported.

Hard limits on the other end

• 2 KB cap per server on tool descriptions and instructions (v2.1.84+) — verbose servers can't flood the context
• Output warning at 10,000 tokens, truncation at 25,000 (raise via MAX_MCP_OUTPUT_TOKENS)
• Results over 50,000 characters are persisted to disk instead of held in context

{
  "allowedMcpServers": [
    { "serverName": "github",
      "serverUrl": "https://api.github.com/mcp" },
    { "serverName": "company-internal",
      "serverCommand": "company-mcp-server" }
  ],
  "deniedMcpServers": [
    { "serverName": "untrusted-*" },
    { "serverUrl": "http://*" }
  ]
}

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json · Linux: ~/.config/ClaudeCode/ · Windows: %APPDATA%\ClaudeCode\
• Allowlist + blocklist match by server name, command, and URL patterns
• Enforced before user configuration — unauthorized servers never connect
• allowAllClaudeAiMcps permits claude.ai connectors organization-wide (v2.1.149+)

servers/
├── google-drive/
│   ├── getDocument.ts   // typed wrapper
│   └── index.ts
└── salesforce/
    └── updateRecord.ts

// agent-written orchestration:
const transcript = (await gdrive
  .getDocument({ documentId: 'abc123' })).content;
await salesforce.updateRecord({
  objectType: 'SalesMeeting',
  data: { Notes: transcript }  // never touches context
});

• Progressive disclosure — browse the tree, load only the tool definitions needed
• Context-efficient results — filter 10,000 rows in the sandbox, return 5 to the model
• Powerful control flow — loops and retries (e.g. polling Slack for "deployment complete") run in code, no round-trips
• Privacy — PII and sensitive records stay in the execution environment
• State persistence — save intermediate files, build reusable skill functions

# discover instantly, no install
npx mcporter list

# call one tool directly
npx mcporter call linear.create_comment \
  issueId:ENG-123 body:'Looks good!'

// compose in TypeScript
const runtime = await createRuntime();
const gdrive = createServerProxy(
  runtime, "google-drive");