mcp-server-builder

---
name: mcp-server-builder
description: Use when exposing a REST API as an MCP server, building Claude/Codex/Cursor tool integrations, or scaffolding an MCP project from OpenAPI. Python, TypeScript, schema validation, safe evolution.
category: Engineering
version: 1.0.0
tools: []
---

# MCP Server Builder

**Category:** Engineering · **Domain:** AI / API Integration

Design and ship production-ready MCP servers from OpenAPI contracts instead of hand-written one-off tool wrappers. The focus is fast scaffolding, schema quality, validation, and safe evolution — for both Python and TypeScript implementations, with OpenAPI treated as the source of truth.

## Core Capabilities

- Convert OpenAPI paths/operations into MCP tool definitions
- Plan starter server scaffolds (Python or TypeScript)
- Enforce naming, description, and schema consistency
- Check MCP tool manifests for common production failures
- Apply versioning and backward-compatibility rules
- Separate transport/runtime decisions from tool contract design

## When to Use

- Exposing an internal or external REST API to an LLM agent
- Replacing brittle browser automation with typed tools
- Sharing one MCP server across teams and assistants
- Running repeatable quality checks before publishing MCP tools
- Bootstrapping an MCP server from an existing OpenAPI spec

## OpenAPI-to-MCP Method

1. Start from a valid OpenAPI spec as the source of truth.
2. Map each path/operation to an MCP tool definition: tool name, description, and a JSON-schema input/output derived from the OpenAPI schema.
3. Choose a runtime — Python for fast iteration and data-heavy backends, TypeScript for unified JS stacks and tighter frontend/backend contract reuse. Keep the tool contract stable even if the runtime changes later.
4. Decide the naming and auth strategy before drafting server code.
5. Layer endpoint-specific runtime logic on top of the base scaffold.

## Validating Tool Definitions

Before treating a manifest as ready, check for: duplicate tool names, invalid schema shape, missing descriptions, empty required fields, and naming hygiene issues. Treat any of these as a blocker rather than a warning — a manifest with duplicate names or missing descriptions confuses the calling model instead of failing loudly.

## Hardening for Production

- Keep secrets in environment variables, never in tool schemas
- Prefer outbound host allowlists over open proxies
- Use additive-only evolution: add new tools or fields, but never rename or repurpose an existing tool name in place — that silently breaks every agent that already learned it
- Version the tool contract independently from the transport/runtime implementation

Present the resulting manifest, scaffold plan, and validation findings directly in the chat as structured markdown/code blocks; if the work spans multiple concerns (API design, auth, deployment), @mention a teammate to split the review.