mcp_server_builder v1.0.0

name: "mcp_server_builder" description: "Build MCP servers agents actually use. Use when someone asks to create an MCP server, add MCP tools to a service, or debug a server agents find clumsy. Covers tool design for model callers, annotation discipline, error contracts, transport choice, secrets, and testing with real agents."

MCP Server Builder

Purpose

Build an MCP (Model Context Protocol) server that an agent will call repeatedly and correctly. The server exposes tools, resources, or prompts over stdio (local clients) or Streamable HTTP (remote clients). Most servers fail on the same things: descriptions that confuse the caller, missing or dishonest tool annotations, errors that say nothing, and outputs that blow the caller's context budget. This skill exists to prevent all of that.

Workflow

1. Define the job, not the API. List the 3-7 operations the agent actually performs. One tool per operation. Merge tools that are always called together; split tools that are never called together.

1. Pick the SDK and pin it. Python: mcp v2.x (MCPServer, formerly FastMCP; v1.x keeps working on a mcp<2 pin). TypeScript: @modelcontextprotocol/sdk plus zod. Pin the exact version in the manifest and note which SDK major the server targets.

1. Write agent-facing descriptions first. For every tool, write the description before the code. It must say: what it does, when to use it, when NOT to use it, and what the result looks like. See references/tool-design.md.

1. Implement with the discipline list:

• Honest tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) matching what the code actually does. See references/tool-design.md.
• Structured error contract: every failure returns what went wrong and what the caller should do next. No stack traces to the model. See references/tool-design.md.
• Pagination and an output budget on every read path. Default page small (10-25 items). Full bodies come from a dedicated get-by-id tool.
• Secrets from environment variables or a secret manager, never hardcoded and never in tool defaults or logs.
• stdio logging rule: never write to stdout on a stdio server. Log to stderr (logging in Python, console.error() in TS) or to a file.
• Transport independence: tool logic knows nothing about the transport. The entrypoint picks stdio or Streamable HTTP.

1. Scaffold the server. Keep handlers thin; shared helpers own auth, pagination, formatting, and error wrapping. A complete working starter is in references/snippet_server.py (MCPServer, stdio + Streamable HTTP, all patterns applied). It was tested end to end over real JSON-RPC on SDK 2.3.0.

1. Test like a client, then like an agent.

• Protocol check: npx @modelcontextprotocol/inspector against the running server, or a raw JSON-RPC handshake plus tools/list and one tools/call per tool over stdio.
• Agent check: have an agent perform the real task using only the tools, with a cold start. Watch for: the agent calling the wrong tool first (description problem), asking the user for info the tool could fetch itself (missing chaining guidance), or retrying failures blindly (error contract problem). Fix the server, not the agent.

1. Ship with identity. Name, version, and a one-paragraph purpose in the server metadata and README. Remote servers: HTTPS, auth via OAuth 2.1 per the MCP spec, rate limiting. See references/transports-and-auth.md.

Output Contract

A finished MCP server delivers:

• Source that starts clean: python server.py (stdio) and the documented remote command both work.
• A README with install steps, the tool list with one-line descriptions, required env vars, and how to test with the Inspector.
• Every tool verified against the agent check above, not just the protocol check.

Operating Rules

1. Descriptions are the product. If the agent cannot tell when to call a tool, the tool is unfinished.
2. Annotations must be true. Marking a mutating tool read-only trains clients to skip confirmations on side effects.
3. Errors are instructions, not apologies. Say what failed, why, and what the caller should do differently.
4. Never ship a server whose read tools lack pagination or whose outputs are unbounded. Context is the budget.
5. Never hardcode secrets, write logs to stdout on stdio, or let an error path leak a secret into a tool result.
6. Verify against the current SDK docs before copying any signature from memory. SDK majors move (FastMCP became MCPServer in the Python v2 line; transport config moved from constructor to run()).