# mcp-server-builder

> A Claude Code skill that constructs Model Context Protocol (MCP) servers directly from OpenAPI specifications, handling schema generation, manifest validation, and tool wiring so existing APIs become MCP-callable with minimal manual integration work.

**Use case**: Generate an MCP server from an OpenAPI spec instead of writing one by hand

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

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

**Trigger phrases**: "build an MCP server", "convert this OpenAPI spec to MCP", "scaffold MCP from API"

**Source**: [Alireza Rezvani](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/mcp-server-builder)

**License**: MIT

---

## What it does

`mcp-server-builder` takes an OpenAPI spec and produces a working Model Context Protocol server. Instead of writing the schema, manifest, and tool definitions by hand, you point the skill at a spec and get a scaffolded server that exposes the API's endpoints as MCP tools.

The output covers the parts that are mechanical and error-prone when done manually: tool signatures derived from operation IDs, parameter schemas pulled from the spec, response shapes mapped, and a manifest that validates against the MCP standard.

## When to use it

- You have an existing API with an OpenAPI spec and want it accessible via MCP without rewriting it
- You're building several MCP servers and want a consistent baseline you can tweak after generation
- Onboarding into MCP and you want a working example faster than the docs walkthrough provides
- Adapting a third-party API into MCP (the spec is the contract; the skill does the wiring)

When *not* to reach for it:

- The API has no OpenAPI spec (try a manual MCP build, or generate the spec first)
- The MCP server needs custom logic the spec doesn't capture (auth, transformations, fan-out) — the generated scaffold is the floor, not the ceiling
- For very small APIs (1–3 endpoints) the overhead of OpenAPI exceeds the win

## Install

From the [claude-skills repo](https://github.com/alirezarezvani/claude-skills) under `engineering/mcp-server-builder/`. Follow the install pattern documented there.

## What a session looks like

1. **You provide an OpenAPI spec** — file path, URL, or pasted contents.
2. **The skill validates the spec** and surfaces any issues that would block scaffolding (missing operationIds, malformed schemas).
3. **It generates the MCP server**: tool definitions per endpoint, parameter and response schemas, the manifest, and example client code.
4. **You get a working scaffold** ready to run. Typically you then add: auth, environment-specific config, any transformations the API needs.

The discipline: the skill stays close to the spec. It doesn't invent tools the spec doesn't describe; it doesn't bury logic that should be explicit.

## Receipts

**Where it works well:**
- APIs with clean OpenAPI 3.x specs convert cleanly with minimal post-processing
- The validation step catches spec issues you'd otherwise hit at runtime
- Eliminates the tedious schema-translation work that takes 80% of manual MCP build time

**Where it backfires:**
- Specs with custom extensions or non-standard auth patterns require manual cleanup after scaffolding
- For OpenAPI 2.0 / Swagger specs, conversion is patchier — upgrade the spec first
- The generated server is a starting point, not production-ready: env config, logging, and rate-limiting are still on you

**Pattern that works:** use it as the floor for an MCP build. Generate the scaffold, then layer on the API-specific logic that doesn't belong in a spec. The win is skipping the mechanical translation, not the integration work.

## Source and attribution

From [Alireza Rezvani's claude-skills repository](https://github.com/alirezarezvani/claude-skills/tree/main/engineering/mcp-server-builder), part of his Engineering POWERFUL Tier.

License: MIT.

For the canonical install, supported spec features, and updates, defer to the source repo.