Skills wiki

mcp-server-builder

Generate an MCP server from an OpenAPI spec instead of writing one by hand

License MIT
First documented
MCPOpenAPIScaffolding

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

  • build an MCP server
  • convert this OpenAPI spec to MCP
  • scaffold MCP from API

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 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, part of his Engineering POWERFUL Tier.

License: MIT.

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