---
name: mcp-builder
description: Build MCP (Model Context Protocol) servers — stdio, HTTP/SSE, or remote. Covers tool design, auth, deployment, and testing.
---

# MCP Builder Skill

Use when building a new MCP server or adding tools to an existing one.

## MCP Server Types
- **stdio** — subprocess, local only, simplest
- **HTTP/SSE** — network accessible, supports auth, deployable
- **Remote (Cloudflare Workers, etc.)** — edge-deployed, global

## Tool Design Principles
1. **One tool = one atomic action.** Don't bundle list+get into one tool.
2. **Names are verbs**: `get_user`, `list_orders`, `create_invoice`.
3. **Required params only** — use optional sparingly with sensible defaults.
4. **Return structured JSON** — always. Never plain strings.
5. **Descriptive tool descriptions** — the model reads these to decide which tool to call.
6. **Error objects not exceptions** — return `{error: "message"}` in the result, don't throw.

## Minimal stdio Server (Node.js)
```js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

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

server.setRequestHandler("tools/list", async () => ({
  tools: [{ name: "say_hello", description: "Say hello", inputSchema: {
    type: "object", properties: { name: { type: "string" } }, required: ["name"]
  }}]
}));

server.setRequestHandler("tools/call", async (req) => {
  if (req.params.name === "say_hello") {
    return { content: [{ type: "text", text: `Hello, ${req.params.arguments.name}!` }] };
  }
  throw new Error(`Unknown tool: ${req.params.name}`);
});

await server.connect(new StdioServerTransport());
```

## Auth (HTTP servers)
- Static API key: `Authorization: Bearer <key>` header check
- OAuth 2.1 with PKCE for user-facing servers
- Never put secrets in tool responses

## Testing
```bash
# Test with MCP inspector
npx @modelcontextprotocol/inspector node ./server.js

# Test tool call directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"say_hello","arguments":{"name":"world"}}}' | node server.js
```

## .mcp.json Registration
```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"]
    }
  }
}
```