MCP — Model Context Protocol

1. What MCP is (and isn't)

MCP is a JSON-RPC-based protocol Claude speaks to external processes. Those processes (called servers) expose three things:

• Tools — functions Claude can call (e.g., github.create_pr, postgres.query).
• Resources — data Claude can read (a file, a row, a doc).
• Prompts — pre-baked prompt templates the server suggests.

Most servers focus on tools. That's where the action is.

2. How an MCP server works

An MCP server is just a program that speaks the protocol on one of two transports:

• stdio — Claude spawns the process and pipes JSON-RPC over stdin/stdout. Most local servers.
• HTTP / SSE — the server runs as a web service; Claude connects over the network. Used for shared servers and connectors on claude.ai.

When you connect a server, Claude reads its tool list at startup and can then call any of those tools mid-conversation — same as the built-in Bash, Read, Edit tools.

3. Installing servers in Claude Code

One-line install

# official Postgres server
claude mcp add postgres @modelcontextprotocol/server-postgres \
  --env POSTGRES_URL="postgres://localhost/mydb"

# GitHub
claude mcp add github @modelcontextprotocol/server-github \
  --env GITHUB_TOKEN="ghp_..."

Manual configuration

Edit ~/.claude/mcp.json (or the project-level .mcp.json):

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgres://localhost/mydb"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    }
  }
}

Verify

claude mcp list

Each connected server shows up with its tool count. Inside Claude Code, you can also run /mcp list.

User-scope vs project-scope

4. Installing in claude.ai

On claude.ai, MCP servers are surfaced as Connectors.

1. Settings → Connectors.
2. Browse the catalog (Google Drive, Calendar, GitHub, Linear, Notion, Figma, etc.) or Add custom connector with an HTTP/SSE endpoint.
3. Authenticate (usually OAuth). Toggle the connector on per chat from the paper-clip menu.

5. The essentials (install these first)

Three servers cover 80% of pro workflows.

6. Developer-focused servers

7. Productivity & team tools

8. Data & analytics

9. Design tools

10. Build your own MCP server

The fastest path is the official TypeScript SDK. Five-minute "hello tool":

npm create mcp-server@latest my-server
cd my-server
npm install

// src/index.ts
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: "0.1.0" });

server.tool(
  "current-weather",
  "Return the current weather for a city.",
  { city: z.string() },
  async ({ city }) => ({
    content: [{ type: "text", text: `It's 72°F and sunny in ${city}.` }],
  })
);

await server.connect(new StdioServerTransport());

Build and connect:

npm run build
claude mcp add my-server node /absolute/path/to/dist/index.js

Now your tool is callable from any Claude Code session. Pro patterns:

• Validate inputs with zod — schemas double as the tool documentation Claude sees.
• Return structured content when you can (text + JSON), not just stringified blobs.
• Read-by-default, write-on-confirm — for any destructive action, require an explicit confirm: true argument.
• Log to stderr, not stdout — stdout is the JSON-RPC channel. Logging to stdout breaks everything.
• Use HTTP transport when the server is shared (one process, many users).

For the official scaffolder skill, install mcp-builder and ask Claude to make you one in plain English.

11. Security & trust

• Use fine-grained tokens. GitHub: limit to specific repos. AWS: use a session token with a tight IAM policy. Stripe: restricted keys per use case.
• Set permissions.deny in settings.json for any MCP tool that shouldn't be auto-callable in your environment.
• For sensitive workflows, use project-scope MCP so the connection only loads in the relevant repo.
• When the server is community-built, run it in a container or restricted user account.