Build, iterate, and evaluate Model Context Protocol (MCP) servers that expose external services as tools an LLM can call. Covers schema/tool design, error handling, pagination, MCP Inspector testing, and an eval set.
SkillScore91Maintained
Automatic
◆AI Engineer pack
Last verified 10/8/2026
What it changes
Passed 20 of 22 test cases with the skill, and 13 of 22 without it.
Without skill59%
With skill91%
Checks it passed that the model alone missed
Specifies exactly 10 evaluation questions in evals.xml.
Requires producing a one-page design brief before writing code.
Requires marking required fields explicitly in the JSON schema.
and 7 more in the full report
7 fixed13 passed either way2 still failing0 broke
Pass-rate lift
+32 pp
Tokens
+42%
Agent turns
0%
Response time
-28%
Model gemini-3.6-flashMeasured 10/8/2026v220 of 22 cases passed with skill
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 7 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 7
Prompt
Before writing any server code for a multi-tenant CRM API, what initial planning document should be produced and shared with the team to align on scope and tools?
What was checked, without and with the skill
Checked
Without skill
With skill
Requires producing a one-page design brief before writing code.
Missed
Passed
Requires including proposed tools and design trade-offs in the brief.
Passed
Passed
case-15 · gemini-3.6-flash · 10/8/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md117 linessingle file
Invocation points:
User describes a service or API they want an LLM to reach
/gsd mcp init scaffolds config but there's a tool integration to build
Replacing a hand-rolled extension with a standard MCP server
<core_principle>
THE QUALITY METRIC IS TASK COMPLETION, NOT SCHEMA VALIDITY. A server that lists 30 tools with cryptic names and empty descriptions passes the protocol but fails the point. The tool description is the only thing an LLM has to decide whether to call it — write it like documentation for a stranger under time pressure.
DESIGN FOR THE MODEL, NOT THE API. A raw REST endpoint is rarely the right tool. Group, filter, and pre-shape responses so the model gets what it needs to reason, not a 40KB JSON blob it has to summarize. Fewer, deeper tools beat many, shallow ones.
</core_principle>
Step 1: Research and scope
Study modern MCP design. Read the latest MCP protocol docs (not training data — fetch them). Read 2–3 reference implementations to see current patterns.
Pick a framework. TypeScript is the default — the reference SDK is the most mature. Python is fine for data-heavy or ML adjacencies.
Analyze the target API. Map the external service's endpoints, auth, rate limits, pagination, error shapes. Identify what a human workflow on top of it actually looks like — that's the cut line for tool design.
Produce a brief. One page: what the server does, who calls it, the 5–10 tools you plan to expose, and the top 3 design trade-offs. Confirm with the user.
Step 2: Set up the project
Skeleton:
server/
src/
index.ts # MCP entry point — stdio or sse transport
client.ts # API client with auth, retries, typed errors
tools/ # one file per tool, or grouped by domain
pagination.ts # shared cursor handling
Guide the creation of high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when the user wants to build an MCP server to integrate an external API or service, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).