MCP (Model Context Protocol) — Advisor & Reference

Specification: https://modelcontextprotocol.io/specification/2025-11-25 (November 2025)

When to Use MCP (Decision Tree)

Rule of thumb: Use MCP when (1) an official/community server exists, (2) you need audit/permission control, or (3) you’ll reuse the integration across sessions.

Quick Start (Local stdio via npx)

1. Create or edit .claude/.mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "POSTGRES_URL": "${DATABASE_URL}" }
    }
  }
}

2. Validate the connection:

export DATABASE_URL="postgresql://user:pass@localhost:5432/db"
claude mcp list
claude mcp get postgres

Common Tasks

Add a database connection

# PostgreSQL
claude mcp add postgres --env POSTGRES_URL=postgresql://user:pass@host:5432/db -- npx -y @modelcontextprotocol/server-postgres

# SQLite (local file)
claude mcp add sqlite -- npx -y @modelcontextprotocol/server-sqlite ./data/app.db

Add GitHub integration

claude mcp add github --env GITHUB_TOKEN=ghp_xxx -- npx -y @modelcontextprotocol/server-github

Add filesystem access (scoped)

# Read-only access to ./docs
claude mcp add docs-readonly --deny "mcp__filesystem__write_file" -- npx -y @modelcontextprotocol/server-filesystem ./docs

Add remote server (HTTP transport)

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

Add PostHog MCP (EU/US + Codex fallback)

Use the region-matching PostHog MCP host:

• EU workspaces: https://mcp-eu.posthog.com/mcp
• US workspaces: https://mcp.posthog.com/mcp

# Codex streamable HTTP (default)
codex mcp add posthog --url https://mcp-eu.posthog.com/mcp
codex mcp login posthog

# If Codex fails at initialize with HTTP 500, use SSE bridge fallback
codex mcp remove posthog
codex mcp add posthog -- npx -y mcp-remote@latest https://mcp-eu.posthog.com/sse

The SSE bridge keeps PostHog available in Codex when streamable_http handshakes fail.

Permission Management

# Allow all tools from a server (wildcard)
claude mcp add --allow "mcp__postgres__*" postgres -- npx -y @modelcontextprotocol/server-postgres

# Allow specific tools only
claude mcp add --allow "mcp__postgres__query,mcp__postgres__list_tables" postgres -- npx -y @modelcontextprotocol/server-postgres

# Deny a specific tool
claude mcp add --deny "mcp__filesystem__write_file" filesystem -- npx -y @modelcontextprotocol/server-filesystem ./data

Build vs Use Decision

Build Custom MCP Server (Quick Start)

When no existing server fits your needs, build a custom one:

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk

Minimal TypeScript server (src/index.ts):

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Define tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "my_tool",
    description: "What this tool does",
    inputSchema: {
      type: "object",
      properties: { query: { type: "string" } },
      required: ["query"]
    }
  }]
}));

// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "my_tool") {
    const result = await doWork(request.params.arguments);
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

const transport = new StdioServerTransport();
await server.connect(transport);

Register in .claude/.mcp.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["tsx", "./my-mcp-server/src/index.ts"],
      "env": { "API_KEY": "${MY_API_KEY}" }
    }
  }
}

Full guide: references/mcp-custom.md (TypeScript + Python, resources, prompts, testing, deployment)

Production Guardrails (Required)

• Assume tool outputs are untrusted (prompt injection). Sanitize/structure before reuse.
• Default to least privilege: read-only DB, scoped filesystem allowlists, minimal tool allowlists.
• Keep secrets out of .mcp.json; inject via env vars or a secret manager at runtime.
• Add timeouts, retries, and rate limits; log all tool invocations for audit.

Troubleshooting

What To Read Next

Related Skills

Operational Reliability Addendum (Feb 2026)

MCP Health Gate (Run Before Data Work)

For each MCP server used in a task, run:

1. Presence: codex mcp list
2. Auth state: codex mcp get <server> or equivalent
3. Minimal smoke test: one low-cost read/list call

Only proceed to analysis/query work after all 3 pass.

Transport/Auth Fallback Playbook

If login/initialize fails:

1. verify endpoint region (EU vs US),
2. verify transport support (streamable HTTP vs SSE bridge),
3. retry with documented fallback transport,
4. re-run health gate.

MCP Incident Note Template

When MCP setup fails, report in one block:

• server name,
• endpoint/transport used,
• exact failure message,
• next fallback attempted,
• final status.

Auth Error Escalation (1-Retry Max)

When an MCP tool call fails with an auth/token error:

1. Retry once after re-authenticating (codex mcp login <server> or equivalent).
2. If the retry also fails, stop immediately and notify the user with:
   • server name,
   • exact error message,
   • what was attempted.
3. Do not loop retries — auth failures that survive one re-auth are environment/config issues that require human intervention.

Unbounded auth retry loops waste context window and block productive work.

Reuse Rule

Cache working MCP connection settings per session and avoid repeated re-login/reconfigure unless health gate fails.