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)

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, action-oriented name. (mcp-builder has the full tool-design rubric; apply it here.)
3. Decide read vs write. Mark which tools are read-only and which mutate state; this becomes the readOnlyHint / destructiveHint annotations later.
4. Scope the secrets. What credentials does each tool need? For "Just me" they live in local env. For hosted, they live server-side and must never be passed through from the client (see scaling.md).
5. Now ask the language question (Phase 0 Q3) if it was deferred, recommending based on what you found.

Deliverable: a numbered list of proposed tools, each with name, one-line purpose, inputs, read/write, and the service call it makes. Confirm with the user before building.