# mcp-builder

> A Claude Code agent persona for designing, building, and testing MCP servers — with strong opinions on tool naming, typed parameters via Zod or Pydantic, and structured error returns over crashes.

**Use case**: Build MCP servers with agent-friendly tool interfaces, not just working ones

**Canonical URL**: https://agentcookbooks.com/skills/mcp-builder/

**Topics**: claude-code, skills, mcp

**Trigger phrases**: "build an MCP server", "wrap this API as an MCP tool", "design MCP tools"

**Source**: [Michael Sitarzewski](https://github.com/msitarzewski/agency-agents/blob/main/specialized/specialized-mcp-builder.md)

**License**: MIT

---

## 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](https://github.com/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](https://github.com/msitarzewski/agency-agents/blob/main/specialized/specialized-mcp-builder.md).

License: MIT.

Distinct from the wiki's other MCP entry — Rezvani's [`mcp-server-builder`](/skills/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`.