mcp-builder

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• build an MCP server
• wrap this API as an MCP tool
• design MCP tools

What it does

mcp-builder is the MCP-server-development persona in the agency-agents collection. Unlike a generic “build a server” prompt, it treats tool descriptions as UI copy: every word matters because the agent reads them to decide what to call. The persona enforces eight rules — descriptive verb_noun tool names, typed parameters via Zod (TypeScript) or Pydantic (Python), structured JSON output, isError: true on failure instead of crashes, stateless tools, env-var-based secrets, one responsibility per tool, and real-agent testing.

The opinion that makes it different from the SDK docs: “search_orders_by_date” beats “query,” and shipping three well-designed tools beats fifteen confusing ones. The persona rewrites tool descriptions until an agent can pick the right one from name and description alone.

When to use it

• Building a new MCP server from scratch — REST API wrap, database access, internal SaaS integration
• Refactoring an existing server where agents keep picking the wrong tool
• Reviewing tool schemas before they ship — the persona will push back on query, mode, and overloaded parameters
• Pairing with mcp-server-builder (Rezvani) which covers similar ground from a different angle

When not to reach for it:

• You just need a one-shot script — MCP server overhead isn’t worth it
• The integration is already a clean OpenAPI spec and you want auto-generation rather than hand-designed tool shapes
• Stateful, long-running operations — the persona’s “stateless tools” rule will fight you, and you may need a different transport than stdio anyway

Install

From msitarzewski/agency-agents at specialized/specialized-mcp-builder.md. Copy to ~/.claude/agents/ or use the repo’s installer. Standalone — doesn’t depend on the rest of the agency-agents collection.

What a session looks like

1. Capability discovery. What does the agent currently not know how to do? What’s the external system, the auth model, the rate limits? Decide between tools (actions), resources (context), and prompts (templates).
2. Interface design. Name every tool as verb_noun. Write the description first — if you can’t explain when to call it in one sentence, the tool needs splitting. Define parameter schemas with types, defaults, and field-level descriptions.
3. Implementation. Build with the official SDK (TypeScript or Python). Wrap every external call in try/catch and return isError: true with an actionable message. Validate inputs at the boundary. Pull secrets from env vars.
4. Agent testing. Connect the server to a real Claude Code instance. Watch what tool the agent picks. If it picks wrong, the description is wrong — rewrite, don’t blame the agent. Test error paths: API down, bad credentials, rate limits, empty results.
5. Iterate on naming. This is where most bugs live. The persona will keep pushing on tool names and descriptions until the agent picks correctly on the first try in >90% of cases.

The discipline that makes it work: step 4. Tool definitions that look right on paper but confuse the agent in practice are broken — and the only way to catch that is to wire it up and watch.

Receipts

TODO — to be filled in from a real MCP-server build. Once the persona has been used end-to-end on at least one server, this section will capture: how many naming iterations it took to hit a clean agent pick rate, which Zod/Pydantic patterns the persona pushed for, and whether the eight rules held up or got bent in production.

Source and attribution

From Michael Sitarzewski’s agency-agents repository.

License: MIT.

Distinct from the wiki’s other MCP entry — Rezvani’s mcp-server-builder covers production hardening (security, observability, deployment). This persona focuses earlier in the pipeline: interface design and agent-friendliness. The two compose well — design with mcp-builder, harden with mcp-server-builder.