mcp-server-spec

MCP Server Spec Skill

Every SaaS is shipping an MCP server; most dump their REST API as forty tools and wonder why agents flail. This skill designs the server as what it actually is: a user interface for a non-human user — few tools, task-shaped, with descriptions written for a model deciding under uncertainty.

What This Skill Produces

• A toolset design: 3-10 tools mapped to agent tasks, not API endpoints
• Per-tool specs: name, description (the routing surface), parameters, returns, error behaviour
• Auth & scoping decisions: how credentials flow, what a token can never do
• An explicit not-exposed list with reasons — the most load-bearing section
• A test plan: the agent-eval loop that proves the toolset works

Required Inputs

Ask for (if not already provided):

• The product and what users hire it for (the top 5 jobs, not the feature list)
• The existing API surface (endpoints or capability list) if one exists
• Who the agent acts for — the end user's own account? a service account? multi-tenant?
• The riskiest actions the product supports (deletes, sends, payments, permission changes)

Design Method

1. Start from agent tasks, not endpoints. List the 5-8 things an agent will actually be asked to do with this product ("file an expense", "find last quarter's report", "summarise ticket history"). Each becomes one tool — even if it spans four API calls internally. An endpoint-mirrored toolset makes the agent do your orchestration; a task-shaped one does it for them.
2. Keep the toolset small. Every tool dilutes selection accuracy on every call. Target ≤10; past ~15, split into separately-loadable servers by workflow. Merge list/get/search variants behind one tool with parameters where natural.
3. Write descriptions as routing surfaces. The description is all the model sees when choosing. Formula per tool: what it does (one clause) · when to use it and when to use the sibling tool instead · what it returns. Test: could a model pick correctly between your two closest tools from descriptions alone?
4. Design returns for context windows. Return the 6 fields an agent needs, not the 60 the API has; include stable IDs for chaining; paginate with explicit has_more; keep any response under ~2k tokens by default with an opt-in for detail.
5. Make errors instructive. An agent retries what it understands: "date must be YYYY-MM-DD" beats 400 Bad Request. Every error names the parameter at fault and the fix.
6. Draw the safety boundary. Classify every capability: expose (read/create, low blast radius) · expose gated (destructive/outward-facing — require an explicit confirmation parameter and document that clients should surface approval) · never expose (auth changes, deletes without recovery, bulk exports of other users' data). The never-list ships in the spec with reasons.
7. Specify auth honestly. OAuth per end user (agent acts as the user, inherits their permissions) vs API key (service account — then per-tool scoping matters more). State token lifetime, revocation, and what happens mid-session on expiry.

Output Format

MCP Server Spec: [product]

Agent jobs served: [the 5-8 tasks] · Tool count: [n] · Auth: [model + scoping]

Tools

| Tool | Description (as shipped) | Key params | Returns | Risk class |

|---|---|---|---|---|

Gated actions: [which tools require confirmation params, and the expected client behaviour]

Never exposed: [capability → reason] (one line each; this list is reviewed like an API contract)

Error design: [the error shape + 3 example messages]

Test plan: [10-15 realistic agent prompts spanning the jobs; run against a real client; a tool whose description gets misselected twice gets rewritten, not documented around]

Quality Checks

• [ ] Every tool maps to an agent task; no tool exists because "the endpoint was there"
• [ ] Any two sibling tools are distinguishable from their descriptions alone
• [ ] Default responses fit comfortably in a context window (≤~2k tokens)
• [ ] Every destructive or outward-facing action is gated or on the never-list
• [ ] Errors name the offending parameter and the fix
• [ ] The spec includes the agent-eval test plan, not just the schema

Anti-Patterns

• [ ] Do not mirror the REST API — 40 endpoint-tools is the #1 way MCP servers fail
• [ ] Do not write descriptions for developers ("wraps the /v2/items endpoint") — write them for a model choosing a tool
• [ ] Do not return full API payloads — context windows are the scarce resource
• [ ] Do not expose destructive actions ungated because "the client will be careful"
• [ ] Do not skip the never-exposed list — an MCP server without one hasn't been threat-modelled
• [ ] Do not ship without running the agent test plan — schema-valid and agent-usable are different properties