mcp-server-builder

---
name: mcp-server-builder
description: Design high-quality MCP servers around workflows, narrow schemas, context-aware outputs, and actionable errors. Use when building or reviewing MCP tools for real agent tasks.
---

# MCP Server Builder

Use this skill when designing or implementing an MCP server.

## When to Use

- Building a new MCP server from scratch.
- Refactoring a weak or over-thin MCP tool surface.
- Reviewing whether a server exposes the right workflows.
- Designing evaluation cases for MCP usability.

## Core Principles

- Build **workflow tools**, not thin endpoint wrappers — one tool should complete a meaningful agent task, not expose a single API method.
- Keep input schemas **narrow and typed** — reject unknown fields; use enums over free strings where possible.
- Return **high-signal, size-bounded outputs** — default to concise; add `detail` or `verbose` flags when larger payloads are occasionally useful.
- Make error messages **corrective** — tell the agent what to do next, not just what went wrong.
- Prefer **human-meaningful identifiers** over opaque IDs when both are available.
- Design **evaluation cases** before declaring the server "done".

## Workflow

### 1. Map the workflow

- Identify the real tasks an agent must complete, not the underlying API surface.
- Merge low-level steps into meaningful operations (e.g., one `create_and_publish` tool instead of separate `create`, `validate`, `publish`).

### 2. Design the tool surface

```
tool name:    stable, verb-noun, describes the workflow step
input schema: typed, narrow, required fields only + optional detail flags
output shape: consistent structure across all tools in the server
failure modes: named error codes + correction hint
```

### 3. Design for context limits

- Default response fits in ~500 tokens for list operations, ~1500 for detail operations.
- Add `limit`, `page`, or `summary` parameters for large result sets.
- Truncate deterministically (e.g., top N by recency) — never truncate randomly.

### 4. Design corrective errors

Bad error: `"Error: 404 Not Found"`

Good error: `"Resource 'project-123' not found. Use list_projects to see available project IDs."`

Every error should tell the agent its next valid action.

### 5. Implement shared infrastructure first

- Auth handling and token refresh.
- Retry logic with exponential backoff and rate-limit awareness.
- Pagination helpers.
- Output formatting helpers (consistent truncation, redaction of secrets).

### 6. Evaluate before shipping

- Write representative task scenarios (not unit tests for individual tools).
- Check whether an agent can complete the full workflow using only the exposed tools.
- Redesign weak tools before adding more tools — more tools is not always better.

## Server Readiness Checklist

- [ ] Every tool completes a meaningful workflow step.
- [ ] All inputs are typed and schema-validated.
- [ ] Output size is bounded by default.
- [ ] All error messages include a correction hint.
- [ ] Auth and retry are handled in shared infrastructure.
- [ ] At least one end-to-end task scenario has been tested.
- [ ] No secrets appear in tool outputs or error messages.

## Local References

- `reference/mcp_best_practices.md`
- `reference/python_mcp_server.md`
- `reference/node_mcp_server.md`
- `reference/evaluation.md`

Use the Python and Node references only for the stack you are actually shipping.

## Bundled Scripts

- `scripts/evaluation.py` — evaluation scaffolding
- `scripts/connections.py` — connection-oriented examples

Use them as optional helpers, not mandatory runtime requirements.