MCP Guide

MCP (Model Context Protocol) is an open standard for connecting AI agents to external tools and data sources. Think of it as USB for AI — a universal connector.

How It Works

[AI Agent] <--MCP--> [MCP Server] <---> [External System]
                                         (Database, API, File System, etc.)

The agent sends requests to MCP servers, which translate them into actions on external systems. The agent never touches the external system directly.

Key Concepts

Server — A program that exposes tools (functions the agent can call) and/or resources (data the agent can read). Runs locally or remotely.

Tool — A callable function with a defined schema. Example: query_database(sql: string).

Resource — Read-only data exposed to the agent. Example: a file's contents, a database schema.

Transport — How the agent communicates with the server. Options: stdio (local process), HTTP/SSE (remote).

Popular MCP Servers

Canonical (currently maintained)

These are the reference + widely-used servers most agents pick up first:

Vendor / SaaS integrations

Project-specific examples

Tools that happen to ship MCP servers for their own use — adopt selectively:

Archived — avoid

As of 2025–2026, several 2024-era reference servers have been moved to modelcontextprotocol/servers-archived and are no longer maintained:

Postgres, Slack, Sentry, GitHub (reference), Puppeteer, SQLite, Redis, Google Drive, Google Maps, Brave Search, EverArt, AWS KB Retrieval.

Use community-maintained forks or first-party replacements (e.g. GitHub Copilot MCP, Vercel MCP, Sentry's newer MCP, community Postgres MCPs).

Configuring MCP in Claude Code

Create .mcp.json at project root:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Or add via CLI:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "$PWD"

Building an MCP Server

A minimal MCP server in TypeScript:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({ name: 'my-server', version: '1.0.0' });

server.tool('greet', { name: z.string() }, async ({ name }) => ({
  content: [{ type: 'text', text: `Hello, ${name}!` }],
}));

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main();

The TypeScript SDK uses the Standard Schema spec — bring Zod, Valibot, or ArkType.

Tips

Transport choices

• stdio — spawns the server as a child process, communicates over stdin/stdout. Best for local dev and single-user CLI tools. No auth surface, no network exposure.
• HTTP / SSE — long-lived connection for remote servers. Pick this when you want a single MCP server to serve multiple users or multiple machines. Needs auth.
• Streamable HTTP — newer transport that replaces SSE. Single request/response path, works over standard HTTP proxies, supports session resumption.

For local personal agents default to stdio. For team/shared servers use Streamable HTTP.

Auth

• stdio has no auth — the child process inherits your shell env. Keep secrets in env vars the server reads (DATABASE_URL, API keys, etc.).
• HTTP and Streamable HTTP servers should use OAuth 2.0 for production. The MCP spec documents an OAuth flow; several client libraries handle it transparently.
• Never expose an HTTP MCP server to the public internet without auth — the agent's capabilities become the attacker's capabilities.

Security boundaries

Every MCP server is an extension of the agent's blast radius. A filesystem server gives the agent filesystem access; a git server gives it repo-rewrite power.

• Scope filesystem servers to a specific root directory — never to / or $HOME.
• Review what tools a server exposes before adding it — read the list_tools output.
• In shared/team setups, use the MCP server's own allowlist + the client's permissions.deny in .claude/settings.json as defense in depth.

Performance

• Every active server adds tokens to the system prompt (tool schemas, descriptions). Cap at 5–6 active servers per session.
• Lazy-load servers where the client supports it — some clients load tools on first use rather than at session start.
• Test servers independently (npx -y <server> --help) before wiring them into the agent.
• Check modelcontextprotocol/servers for the official registry.