build-mcp-server

name	build-mcp-server
description	This skill should be used when the user asks to "build an MCP server", "create an MCP", "make an MCP integration", "wrap an API for Claude", "expose tools to Claude", or discusses designing an MCP server. It selects a deployment, language, and tool surface, then routes to the focused MCP skills.
version	0.2.0

Build an MCP Server

Provenance: Forked from anthropics/claude-plugins-official/plugins/mcp-server-dev under Apache-2.0. Significant changes: rewritten for MCP 2026-07-28, the v2 SDK families, and this repository's skill artifacts. See ../THIRD-PARTY-NOTICES.md.

Design before scaffolding. Determine the upstream system, users, deployment, required interaction model, and authorization boundary. Do not expose an upstream API wholesale or invent transport state that the protocol no longer has.

Modern model: 2026-07-28

Modern MCP has no initialize / notifications/initialized handshake and no HTTP session. server/discover is an optional capability query, not negotiation. Every modern request carries _meta containing:

• io.modelcontextprotocol/protocolVersion
• io.modelcontextprotocol/clientCapabilities
• normally io.modelcontextprotocol/clientInfo

HTTP is stateless: do not mint, echo, or rely on Mcp-Session-Id. Persist application state in a database and return explicit, authorization-checked handles such as jobId or basketId as normal tool arguments.

For a multi-step interaction, return MRTR resultType: "input_required"; the client supplies inputResponses and reissues the original operation with a new JSON-RPC ID. Servers MUST NOT initiate JSON-RPC requests in the modern model. Treat requestState as attacker-controlled: integrity-protect it, bind it to the principal and originating request, and expire it.

Use references/dual-era.md when a server or client must support both the 2025 handshake era and the 2026 modern era.

1. Establish the design brief

Ask these questions together; skip answers already supplied:

1. What is the upstream boundary? Cloud API, local filesystem/process, or pure logic?
2. Who installs or reaches it? One developer, an organization, or arbitrary users?
3. How large is the action surface? Fewer than 15 clear actions, or a catalogue?
4. Does a call need user input, host-model work, workspace roots, or a rich UI? Use MRTR for input; use an MCP App only for a real visual workflow.
5. What authenticates to the upstream system? None, API key, or OAuth?
6. Which era must interoperate? Modern-only is the safe default for a new remote server. Use dual-era only for identified legacy clients.

2. Choose deployment

Situation	Recommendation	Why
Cloud API, shared service	Remote Streamable HTTP	One deploy, ordinary HTTP scaling, OAuth support
Local filesystem, hardware, desktop app	MCPB or local stdio	The server must run on the user's machine
Personal prototype	Local stdio	Lowest setup cost; state the MCPB upgrade path
Rich interactive visual output	Remote or MCPB MCP App	An iframe is justified only when native text/form UI is insufficient

Remote HTTP is the default for cloud APIs. Put origin/host validation and authentication before the MCP endpoint. Use a separate health endpoint.

3. Choose the surface

• Small API: one tool per action, precise argument schemas, concise action-oriented descriptions.
• Large API: search_actions plus execute_action; return the action ID, description, and parameter schema from search.
• Resources: expose read-oriented, stable context that a host can browse.
• Prompts: expose explicitly user-invoked templates, not hidden tool logic.

Read references/tool-design.md before registering tools. Every 2026 HTTP request requires Mcp-Method; tools/call, resources/read, and prompts/get additionally require Mcp-Name. An HTTP tools/call with x-mcp-header-marked inputs also requires matching Mcp-Param-* values. Invalid declarations make clients drop the tool from tools/list.

4. Pick an SDK deliberately

SDK	Use for	Limits
C# ModelContextProtocol 2.0.0 plus separate Apps/Tasks packages	Full modern coverage: core, stateless HTTP, MRTR, Apps, Tasks	Apps is experimental (MCPEXP003); Tasks tracks a draft extension
Python mcp 2.0.0	Full modern core, MRTR, and Apps	Tasks are not in the official core SDK
TypeScript @modelcontextprotocol/{core,server,client} 2.0.0	Modern core-only servers and clients	Apps and Tasks are not available in the v2 SDK

Do not recommend @modelcontextprotocol/sdk for a new modern TypeScript server, or FastMCP 3.x for a modern Python server. FastMCP 3.x pins mcp<2; its current API is a legacy-era choice.

5. Scaffold the selected path

1. Use references/remote-http-scaffold.md for a modern core server.
2. Use build-mcp-app only after confirming that an iframe is necessary. Its browser bundle remains legacy-v1 ext-apps; its server may be C# or Python v2.
3. Use build-mcpb for packaged local distribution.
4. Use build-mcp-server-dotnet for C# authoring, Apps, Tasks, AOT, or Microsoft.Extensions.AI integration.
5. Use mcp-tasks for the draft Tasks extension, mcp-2026-migration for an older implementation, and mcp-conformance for HTTP conformance work.

When routing, pass the chosen deployment, upstream auth model, era, language, tool pattern, and any required extensions. Do not make the next skill rediscover them.

6. Validate before deployment

For a modern HTTP server:

• server/discover returns the server's modern support when called.
• Every request validates its per-request _meta; MCP-Protocol-Version matches the body.
• tools/list exposes complete schemas and cache metadata; tools/call returns a structured MCP result.
• Required Mcp-Method headers are present on every request; Mcp-Name and declared Mcp-Param-* headers are present where applicable and agree with the body.
• Header mismatch, missing client capability, and unsupported protocol each return HTTP 400 with -32020, -32021, and -32022 respectively.
• No secret, token, or diagnostic data is returned to the model.
• The server has a focused smoke test and, for remote HTTP, a conformance run.

References

• references/remote-http-scaffold.md — v2 TypeScript and official Python HTTP scaffolds
• references/dual-era.md — modern, legacy, and dual-era routing
• references/tool-design.md — tool schemas, descriptions, and header-promoted inputs
• references/elicitation.md — MRTR input flows
• references/server-capabilities.md — deprecations, subscriptions, progress, and cancellation
• references/auth.md — CIMD-first authorization guidance
• references/versions.md — version ledger and runnable verification commands