Understanding MCP

MCP (Model Context Protocol) is the open standard for connecting tools to AI agents. Write or install a server once, and it works in Claude Code, Codex CLI, Grok Build, Gemini CLI, Cursor, Goose, and most other runners. Think "USB for agent capabilities."

Created by Anthropic in late 2024, it's now adopted across the ecosystem — OpenAI, Google, Microsoft, GitHub, and thousands of community servers.

The mental model

Your agent (client)  ←—— MCP protocol ——→  Server (the capability)
   Claude Code                                Playwright (browser)
   Codex CLI                                  GitHub (issues/PRs)
   Grok Build                                 Postgres (your data)
   Cursor…                                    Sentry (prod errors)

A server exposes three kinds of things to the agent:

Tools are what you'll use 95% of the time.

Local vs. remote servers

Remote servers are newer and increasingly preferred for SaaS products — no install, and OAuth beats pasting API keys.

Adding servers, per runner

# Claude Code — local server
claude mcp add playwright -- npx -y @playwright/mcp@latest

# Claude Code — remote server
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Claude Code — with an API key
claude mcp add brave-search --env BRAVE_API_KEY=YOUR_KEY -- npx -y @brave/brave-search-mcp-server

Grok Build is MCP-native — it picks up the same servers with zero reconfiguration, so anything you wired up for Claude Code already works there. Other runners use a JSON config with the same shape — Codex CLI (~/.codex/config.toml), Gemini CLI (~/.gemini/settings.json), Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Tip for teams (Claude Code): check a .mcp.json into your repo root and every teammate gets the project's servers automatically — full example.

A sane starter set

Don't install twenty servers. Each one's tool definitions consume context on every request. Start with:

1. Playwright — a real browser
2. Context7 — current library docs, kills hallucinated APIs
3. GitHub — if your work lives there
4. One data source you actually use — Postgres, Supabase, or Sentry

Add more when a task actually needs them. Browse the full directory.

Security: the part people skip

An MCP server runs with your permissions and feeds output straight into your agent's context. Treat installs like dependencies:

• Prefer official servers (look for the publisher: @modelcontextprotocol/*, @playwright/mcp, GitHub's, Brave's…)
• Prefer read-only modes for data sources — e.g. Supabase's --read-only, Postgres --access-mode=restricted
• Scope filesystem access to specific directories, never /
• Beware tool-output injection: a malicious web page or issue comment can contain instructions your agent might follow. Browsing + private-data + write-access in one session is the risky combination — drop one of the three when handling untrusted content.

Debugging a server that won't work

1. Test it standalone with the official inspector: npx @modelcontextprotocol/inspector npx -y @playwright/mcp@latest — if it fails here, the problem is the server or its env, not your agent.
2. Check the runtime exists — npm servers need Node; uvx servers need uv.
3. Check env vars — most "server crashed" errors are a missing API key. The inspector shows stderr.
4. In Claude Code: /mcp lists servers and their connection status.
5. Tool exists but isn't used? Tell the agent explicitly ("use the playwright tools to…") once; if it works, the tool descriptions may be getting crowded out — remove servers you're not using.