Immutable. This exact content is served forever at /api/v1/blob/8daca2afd9403ced.
---
name: "mcp-authoring"
description: "When to author an MCP server, architecture overview (tools/resources/prompts), stdio vs HTTP+SSE transport tradeoffs, registration in .claude.json. Sub-modules: stdio-server-template.md (full TS code), http-server-on-workers.md (Hono + SSE on CF Workers), forge-mcp-from-openapi.md (extend forge script with --target=mcp-server). Fires when user asks to 'build an MCP server', 'expose X as an MCP tool', or 'add MCP to my Worker'."
when_to_use: "Any request to author, scaffold, or extend an MCP server — whether standalone stdio for local dev tools or HTTP transport on CF Workers for shareable AI integrations."
effort: "high"
model: "sonnet"
priority: 5
pack: "ai"
triggers:
- "MCP server"
- "model context protocol"
- "mcp tool"
- "mcp resource"
- "mcp prompt"
- "stdio transport"
- "claude.json"
- "expose API as MCP"
paths:
- "src/worker/**"
- "workers/**"
- "mcp-server/**"
- ".claude.json"
submodules:
- stdio-server-template.md
- http-server-on-workers.md
- forge-mcp-from-openapi.md
---
# 19 — MCP Authoring
The Model Context Protocol (MCP) is the standard surface for giving AI agents structured
access to external systems. An MCP server exposes three primitive types:
- **Tools** — callable functions with a JSON schema input, returning structured output.
The model decides when to call them. Think: "do something."
- **Resources** — addressable content (files, DB rows, live feeds) returned as text or
binary. The model fetches them. Think: "read something."
- **Prompts** — reusable prompt templates with typed arguments. Think: "fill and inject."
Source authority: modelcontextprotocol.io/introduction, `@modelcontextprotocol/sdk` NPM package.
---
## When to author an MCP server
Build one when:
- An existing REST API or Worker function would provide genuine value to an AI agent but
is not currently reachable as a tool (the cost of schema-wrapping is lower than the
benefit of agent access).
- You need to share a tool set across multiple Claude sessions / Claude Code projects
without copy-pasting prompts.
- A CF Worker already owns the business logic and you want to give Claude persistent,
auth-aware access (HTTP transport on Workers = zero extra infra).
- You are extending the forge pipeline to emit MCP servers from OpenAPI specs
(`--target=mcp-server` flag — see `forge-mcp-from-openapi.md`).
Do NOT build one when a simple `[[hono-api]]` route + direct `curl` / `fetch` suffices —
MCP adds SDK overhead that isn't justified for one-off integrations.
---
## Architecture overview
```
Claude Code / Claude Desktop
│ JSON-RPC 2.0
▼
┌──────────────┐
│ MCP Server │
│ ┌────────┐ │
│ │ tools │ │ ← JSON-schema validated inputs + Zod-validated outputs
│ ├────────┤ │
│ │resourc.│ │ ← URI-addressed, MIME-typed
│ ├────────┤ │
│ │prompts │ │ ← Named templates with typed args
│ └────────┘ │
└──────────────┘
│
▼
External system (D1 / R2 / Vectorize / external API)
```
Every tool input validated with `z.parse()` before hitting the system. Every result
validated before returning. No raw model outputs, no untyped `any`. Per `[[contract-first-ai]]`
and `[[zod-everywhere]]`.
---
## Transport decision
| Criterion | stdio | HTTP + SSE |
|---|---|---|
| Where it runs | Local process, same machine as Claude | Any origin — CF Workers, remote server |
| Auth | None (process-level trust) | HTTP headers, Bearer tokens, CF Zero Trust |
| Session state | Process lifetime | DO / KV per session ID |
| Streaming | Native (stdout) | SSE (`text/event-stream`) |
| Setup | `~/.claude.json` mcpServers entry | CF Worker deploy + `.claude.json` remote entry |
| Best for | Dev tools, local scripts, secret-laden CLIs | Shared team tools, SaaS integrations, per-user auth |
| Per `[[cloudflare-lock-in-is-leverage]]` | Use for purely local utilities | Prefer — CF Workers = zero cold-start, global, cheap |
---
## .claude.json registration
### stdio server
```json
{
"mcpServers": {
"my-local-tool": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/dist/index.js"],
"env": {
"DB_PATH": "/Users/Apple/data/mydb.sqlite"
}
}
}
}
```
### HTTP server (CF Workers)
```json
{
"mcpServers": {
"my-worker-tool": {
"url": "https://my-mcp.workers.dev/mcp",
"headers": {
"Authorization": "Bearer ${MY_MCP_TOKEN}"
}
}
}
}
```
Place at `~/.claude.json` for global registration or `.claude.json` at repo root for
project-scoped registration. Claude Code picks up both.
---
## Sub-modules
- `stdio-server-template.md` — complete TypeScript stdio server with sample tool + resource + prompt
- `http-server-on-workers.md` — Hono + MCP SDK + SSE on CF Workers, wrangler.toml, auth
- `forge-mcp-from-openapi.md` — plan for extending `bin/forge-skill-from-openapi.mjs` to emit MCP servers
---
## Quality gates for every MCP server
1. All tool inputs have a Zod schema — never accept raw `unknown`.
2. All tool results conform to a Zod output schema before returning.
3. Errors return MCP `isError: true` with structured `{ code, message }`, never throw raw JS errors.
4. Every tool has a `description` that an LLM can use to decide when to call it — specific, ≤2 sentences.
5. No secret values in tool schemas or resource URIs — pass via `env` block in `.claude.json`.
6. Smoke-test with `npx @modelcontextprotocol/inspector` before registering.
---
## Cross-links
- `[[cloudflare-lock-in-is-leverage]]` — Workers HTTP transport over any third-party MCP host
- `[[ai-agent-supervisor]]` — MCP tools are the supervised boundary for agent actions
- `[[contract-first-ai]]` — Zod at every tool boundary
- `[[hono-api]]` — HTTP transport built on Hono
- `05-architecture-and-stack/cf-agents-do-pattern.md` — stateful MCP sessions via Durable Objects
- `rules/ai-agent-security.md` — tool scope minimization, input sanitization, rate limiting