build-mcp

# Build MCP

Build a Model Context Protocol (MCP) server the right way, end to end. The defining move of this skill: establish the user's context with `AskUserQuestion` before building anything, then tailor every phase to that context. A personal local server and a public hosted server share almost no steps past "build", so branch early and commit to the branch.

## How this relates to mcp-builder

The Anthropic `example-skills:mcp-builder` skill is the gold-standard reference for the *implementation* itself: FastMCP and TypeScript SDK patterns, tool design, input/output schemas, annotations, error handling, and evaluation. Do not duplicate it. This skill is the **scope-and-distribution wrapper around it**: it decides what to build, for whom, where it runs, and how it ships. When you reach the build phase, invoke `example-skills:mcp-builder` for the deep implementation guidance and keep this skill's references thin.

## The five phases

1. **Analyze**: understand the service to wrap and pick the right tool boundaries.
2. **Build**: scaffold and implement the server (delegates to mcp-builder).
3. **Deploy**: get it running and registered for the target runtime.
4. **Scale**: harden and operate it (only substantive for hosted servers).
5. **Distribute**: make it reachable by the intended audience.

Run them in order. The `AskUserQuestion` answers from Phase 0 gate phases 3, 4, and 5.

## Phase 0: Establish context (AskUserQuestion, do this first)

Before analyzing or writing anything, branch on the user's context. Ask the **audience** question first; it is the headline decision and it cascades into everything downstream. Then ask runtime only if it is still ambiguous, and ask language after Analyze (so you can recommend based on the wrapped service).

**Question 1 (always, ask first): Audience / scope:**

Use `AskUserQuestion`:
- header: "Audience"
- question: "Who is this MCP server for? This decides how we deploy and distribute it."
- options:
  1. "Just me": personal local tool on my machine.
  2. "My team / org": shared internally, installed by colleagues.
  3. "Public / external": published openly for anyone to install.

**Question 2 (conditional): Where it runs:**

Skip for "Just me" (assume local stdio). Ask for org/public when unclear:
- header: "Runtime"
- question: "Where should the server run?"
- options:
  1. "Local stdio": runs as a subprocess on each user's machine. Simplest. Each user supplies their own secrets.
  2. "Hosted HTTP": one Streamable HTTP server many users connect to. Needs auth, deploy, and scaling.

**Question 3 (after Analyze): Language:**

- header: "Language"
- question: "What should the server be written in?"
- options:
  1. "Python (FastMCP)": fastest path, great for wrapping Python-friendly APIs.
  2. "Node / TypeScript (MCP SDK)": the mcp-builder ecosystem default (strongest SDK, models write TS well, best MCPB compatibility). Pick it when torn, or when the service has a strong TS SDK or you ship via npm.
  3. "Recommend for me": pick based on the service analyzed in Phase 1; lean TypeScript unless the wrapped service is clearly Python-friendly.

Ask one question at a time. Confirm the resolved context back to the user in one line before proceeding (e.g. "Building a personal, local, Python stdio server that wraps the Linear API"). That resolved tuple drives the branch table below.

## Branch table (the spine of this skill)

| Phase | Just me (local stdio) | My org (local stdio) | My org (hosted HTTP) | Public (package) | Public (hosted HTTP) |
|-------|----------------------|----------------------|----------------------|------------------|----------------------|
| **Deploy** | `claude mcp add --scope user` or `.mcp.json` | Bundle in a Claude Code plugin; `${CLAUDE_PLUGIN_ROOT}` paths | Deploy Streamable HTTP endpoint + OAuth/bearer | Publish to PyPI/npm; users run via `uvx`/`npx` | Deploy HTTP endpoint; document the URL |
| **Scale** | N/A (keep it maintainable) | N/A per-user; version the plugin | Real: statelessness, sessions, auth, rate limits | Versioning + backward-compat tool changes | Full: statelessness, auth, rate limits, observability |
| **Distribute** | Not shared. Stop after registration. | Org marketplace (`.claude-plugin/marketplace.json` + `/plugin install`) | Org marketplace entry pointing at the hosted URL | PyPI/npm + MCP registry via `mcp-publisher` | MCP registry `remotes` entry + public docs |

If a phase says N/A for the chosen branch, say so explicitly and move on. Do not pad it.

Reference files for each branch:
- **references/transports.md**: stdio vs Streamable HTTP, when each applies, the `http`/`streamable-http` naming gotcha.
- **references/deploy-local.md**: `claude mcp add`, scopes, `.mcp.json`, Claude Desktop config, uvx/npx run configs.
- **references/distribute-marketplace.md**: bundling an MCP server in a Claude Code plugin, org marketplace, the public MCP registry.
- **references/scaling.md**: hosted-server statelessness, sessions, auth, versioning, security.
- **references/python-fastmcp.md** and **references/node-sdk.md**: thin quickstarts that hand off to mcp-builder.

Load only the references the current branch and phase need. Progressive disclosure.

## Phase 1: Analyze

Understand what you are wrapping before you write tools. Output a short tool plan, then confirm it.

1. **Identify the service/API.** Read its docs or SDK. Note auth model (API key, OAuth, none), base URL, rate limits, pagination style.
2. **Pick tool boundaries.** This is a real tradeoff, framed the way mcp-builder frames it: comprehensive API coverage gives agents flexibility to compose operations, while specialized workflow tools are more convenient for specific tasks. Performance is client-dependent (some clients do better with code execution over basic tools, others with higher-level workflows). When uncertain, default to comprehensive API coverage rather than a few workflow tools. Either way each tool does one focused thing with a clear,