MCPForge

Generate MCP servers from OpenAPI specs or docs pages, then verify generated request compatibility before you publish or install them.

Demo

Why It Exists

Most OpenAPI-to-MCP generators stop at endpoint wrappers. That gets you a server, but not necessarily a toolset an LLM can use well. You often end up with hundreds of low-signal tools, weak descriptions, and no clear path from "API surface area" to "jobs a user wants done."

MCPForge does two extra things:

• Curates endpoint tools with AI so the public surface stays small and usable.
• Plans task-oriented workflow tools that wrap useful jobs like find_customers, create_payment_link, or refund_payment.

The result is closer to "brief the model on the jobs it can do" than "dump the entire REST spec into MCP."

Quick Start

Fastest path from the registry:

npx mcpforge add stripe

From an OpenAPI spec:

npx mcpforge init --optimize --workflows https://api.example.com/openapi.json

From a docs page when you do not have a spec:

npx mcpforge init --from-url --workflows https://docs.stripe.com/api

Preview without writing files:

npx mcpforge init --dry-run --optimize --workflows https://api.example.com/openapi.json

Registry

Browse and install community-curated MCP servers:

mcpforge search                     # browse all servers
mcpforge search payments            # search by keyword or tag
mcpforge add stripe                 # generate Stripe MCP server instantly
mcpforge add stripe --pick          # generate and customize tools

Publish your optimized server:

mcpforge auth login                 # one-time GitHub login
mcpforge publish                    # publish from current project dir
mcpforge publish --slug my-api --tags payments,billing

What MCPForge Does

• Parses OpenAPI 3.0, 3.1, and Swagger 2.0 specs from local files or URLs
• Scrapes docs pages and infers an API shape with Claude when no spec exists
• Curates raw endpoints into a smaller endpoint toolset with --optimize
• Plans task-oriented workflow tools with --workflows
• Generates a complete TypeScript MCP server with auth scaffolding and docs
• Detects upstream spec drift and reports risk-scored breaking changes
• Verifies generated request compatibility over stdio with mcpforge test

Feature Overview

• Workflow planning - Generates first-class workflow tools with deterministic step execution. Workflow tools depend on real upstream operations, so drift can be tracked during diff and update.
• AI endpoint curation (--optimize) - Uses Claude to cap noisy APIs to a smaller, better-described public surface. Strict mode defaults to <=25 tools. Standard mode allows broader coverage up to 80.
• Docs URL inference (--from-url) - Scrapes API docs pages and infers endpoints when there is no public OpenAPI spec.
• Interactive selection (--pick) - Lets you choose the exact public tools to expose after planning and optimization.
• Breaking change detection (diff) - Compares stored source IR against the latest upstream spec and reports high, medium, and low-risk changes.
• Workflow-aware update flow (update) - Rechecks upstream APIs, reports workflow impact, and regenerates in place.
• Generated-server verification (test) - Installs dependencies, builds the generated project, validates listTools, and verifies request construction against a local mock upstream before optional live calls.
• Repo-level CI and tests - The repo now includes Vitest coverage for workflow planning, generation, diffing, and selection logic, plus a GitHub Actions workflow.
• Verification-aware publishing (publish) - Public registry publishing now requires a successful verification run by default, and registry entries expose verification metadata to installers.

Commands

Workflow Mode

--workflows adds a planning layer on top of the parsed API:

• MCPForge starts from the parsed endpoint IR.
• If --optimize is enabled, it first curates which endpoints matter most.
• It then plans workflow tools around useful jobs and can keep a few curated endpoint fallbacks when needed.
• Each workflow stores which upstream operations it depends on, so future diff and update runs can report impact when those operations change.

Current workflow execution is intentionally deterministic:

• Linear steps only
• No arbitrary code generation
• Input mapping from workflow inputs and prior step results
• Output selection from saved step results

AI Optimization

Use --optimize with init or generate to run Claude-based endpoint curation.

npx mcpforge init --optimize https://api.example.com/openapi.json

The optimizer:

• Curates to <=25 endpoint tools by default in strict mode
• Rewrites descriptions to be shorter and more LLM-friendly
• Removes admin, health, docs, and other low-value routes
• Prioritizes the endpoints most likely to matter for common user tasks

Use --standard for broader coverage or --max-tools <n> for a custom cap.

Requires ANTHROPIC_API_KEY. If it is missing, optimization is skipped and generation continues.

Configuration

Generated projects include mcpforge.config.json. It stores:

• Spec source and source type
• Output directory
• Optimization settings
• Whether workflow planning is enabled
• Saved public tool selections
• Source IR, optimized IR, planned workflow IR, and final generated IR

That file is what makes generate, diff, and update work without repeating the original setup step.

Testing Generated Servers

Run from inside a generated project:

npx mcpforge test

Or point at a generated project explicitly:

npx mcpforge test --dir ./mcp-server-my-api

By default, mcpforge test:

• runs npm install and npm run build
• starts the generated server over stdio
• verifies listTools matches mcpforge.config.json
• starts a local mock upstream server and points API_BASE_URL at it
• calls each public tool with generated compatibility inputs
• verifies path, query, header, auth, and request-body construction for the supported matrix
• writes verification metadata back to mcpforge.config.json

Use --live only when the generated project's .env is configured and you want real upstream API calls.

Successful verification is what enables mcpforge publish by default.

Compatibility Matrix

Current verified request compatibility covers:

• Auth: header API keys, query API keys, cookie API keys, bearer tokens, and basic auth
• Request bodies: application/json, application/x-www-form-urlencoded, multipart/form-data, text payloads, and binary-compatible payloads
• Verification path: local mock-upstream validation via mcpforge test

Current limitation:

• OAuth token acquisition and refresh are not generated. MCPForge can scaffold token usage when the API presents OAuth as a bearer token, but you must provide and rotate the token externally.

Tested Compatibility

MCPForge has been exercised against real-world specs across different formats and edge cases.

Spec compatibility and runtime verification are separate concerns:

• Spec compatibility: parse, inspect, generate, and compile against varied OpenAPI/Swagger inputs.
• Runtime verification: validate generated request construction against the supported auth/body matrix.

The registry is also the fastest place to find tested, optimized servers that were already run through MCPForge and published for reuse.

Supports OpenAPI 3.0, 3.1, Swagger 2.0, JSON and YAML, circular $refs, and specs with missing operation IDs. The broader compatibility report is in examples/compatibility-report.md.

An example verification output is in examples/verification-report.md.

Contributing

Contributions are welcome. Open an issue for bugs or ideas, or submit a focused PR. Registry contribution rules live in registry/CONTRIBUTING.md.

License

MIT