---
name: mcp-builder
description: "Scaffold a Model Context Protocol server in TypeScript or Python — tools, resources, prompts wired in. Anthropic's MCP server scaffolder. Spins up a production-grade MCP server with tool definitions, resource handlers, prompt templates, and the schema validation that prevents the 'tool returns garbage' bug."
license: MIT
---

# MCP Builder

MCP Builder scaffolds a complete Model Context Protocol server you can run against Claude Desktop, the Claude CLI, or any MCP client — with tools, resources, and prompts already wired into the transport layer. It targets either the TypeScript SDK (`@modelcontextprotocol/sdk`) or the Python SDK (`mcp` / FastMCP), and ships the input schemas that stop a tool from silently returning malformed payloads. It's for developers who want a working server skeleton instead of copy-pasting from the spec.

## When to use it

- You're exposing an internal API, database, or CLI to Claude as callable tools.
- You keep hitting the "tool ran but the model got garbage back" problem and want schema-validated arguments and return shapes.
- You want a server that speaks both stdio (for desktop clients) and HTTP/SSE without rewiring the transport yourself.
- You're prototyping a resource provider (files, records, docs) the model can read on demand.

## What it does

The skill generates a project around the SDK's server primitives. In TypeScript that means a `McpServer` instance with `server.tool(name, zodSchema, handler)`, `server.resource(...)`, and `server.prompt(...)` registrations, plus a `StdioServerTransport` entry point. In Python it scaffolds a `FastMCP` app using `@mcp.tool()`, `@mcp.resource("scheme://{id}")`, and `@mcp.prompt()` decorators. Argument schemas are defined with Zod (TS) or Python type hints / Pydantic, so the runtime rejects bad input before your handler runs. You also get a `package.json`/`pyproject.toml`, a build/run script, and a ready-to-paste `mcpServers` config block for the client.

## Usage

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/mcp-builder/SKILL.md https://claudeskil.com/skills/mcp-builder/SKILL.md
# then, in your project:
claude "scaffold an MCP server in typescript with a tool
        called search_orders that takes a customer_id"
```

Generated TypeScript handler:

```ts
server.tool(
  "search_orders",
  { customer_id: z.string().describe("Customer UUID") },
  async ({ customer_id }) => ({
    content: [{ type: "text", text: await lookup(customer_id) }],
  })
);
```

Register it with the client:

```json
{ "mcpServers": { "orders": { "command": "node", "args": ["dist/index.js"] } } }
```

## Tips & gotchas

- Tools must return a `content` array (`type: "text" | "image" | "resource"`), not a bare string — the scaffold enforces this, but custom edits often break it.
- stdio transport reserves stdout for the protocol. Never `console.log` to stdout in a TS server; use `console.error` or a file logger.
- `describe()` on each Zod field becomes the parameter doc the model sees — fill them in, or tool selection degrades.
- Run `npx @modelcontextprotocol/inspector` against your server to test tools interactively before connecting a client.

## FAQ

**TypeScript or Python?** Both produce equivalent servers. Pick TS for npm-distributed binaries, Python/FastMCP for fewer lines and quick scripts.

**Does it support HTTP, not just stdio?** Yes — request the streamable HTTP/SSE transport and the entry point is generated accordingly.

**How do resources differ from tools?** Resources are read-only context the model pulls by URI; tools perform actions and take arguments.