MCPForge

Turn any API into a secure MCP server in one command.

MCPForge compiles an OpenAPI document into a ready-to-run Model Context Protocol server with typed tools, auth passthrough, read-only mode, rate limits and an audit log. No boilerplate, no hand-written tool schemas.

npx @x123martin/mcpforge-cli init ./openapi.yaml
# [mcpforge] imported 42 tools from ./openapi.yaml
# [mcpforge] base URL: https://api.example.com
# [mcpforge] wrote mcpforge.config.json

npx @x123martin/mcpforge-cli inspect
# [mcpforge] inspector:    http://127.0.0.1:7331
# [mcpforge] MCP endpoint: http://127.0.0.1:7331/mcp

Open the inspector, pick a tool, and call your API. Then point Claude Desktop, Cursor, VS Code, Windsurf or any MCP client at the same server.

Demo

$ npx @x123martin/mcpforge-cli generate examples/petstore.yaml -o examples/petstore.mcpforge.json
[mcpforge] wrote 5 tools to examples/petstore.mcpforge.json
[mcpforge] source: Swagger Petstore v1.0.0
[mcpforge] base URL: https://petstore3.swagger.io/api/v3
[mcpforge] read-only tools: 3/5 (writes are blocked by default)

$ npx @x123martin/mcpforge-cli inspect --manifest examples/petstore.mcpforge.json
[mcpforge] MCP endpoint: http://127.0.0.1:7331/mcp
[mcpforge] inspector:    http://127.0.0.1:7331

To record the animated version, install VHS and run vhs docs/demo.tape. Then replace the transcript with ![MCPForge demo](docs/demo.gif).

Related MCP server: yamcp

Why MCPForge?

Connecting an AI agent to an internal API today means writing a custom MCP server by hand: parsing OpenAPI, mapping schemas, wiring auth, handling errors, pagination and timeouts. It is days of work per API, and most implementations give the agent far more access than it needs.

MCPForge does the boring part in one command and puts a security layer in front of the API:

• Read-only by default. Write tools are hidden and blocked unless you opt in.

• No raw credentials in prompts. Auth is injected by the runtime, never exposed as a tool argument.

• Auditable. Every tool call is logged with secrets redacted.

• Bounded. Per-tool rate limits, request timeouts and response size caps.

• Composable. Works over stdio or Streamable HTTP with any MCP client.

Quickstart (under 2 minutes)

1. Generate a server from an OpenAPI document

npx @x123martin/mcpforge-cli init ./openapi.yaml

init auto-detects openapi.yaml, openapi.json, swagger.json and common variants when no path is given.

2. Inspect and try the tools locally

npx @x123martin/mcpforge-cli inspect

The inspector lists every exposed tool, shows its JSON Schema and lets you call the upstream API from the browser.

3. Add it to your MCP client

stdio (recommended for desktop clients):

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "@x123martin/mcpforge-cli",
        "serve",
        "--manifest",
        "mcpforge.json",
        "--config",
        "mcpforge.config.json"
      ],
      "env": {
        "MCPFORGE_AUTH_TOKEN": "your-token"
      }
    }
  }
}

Streamable HTTP:

npx @x123martin/mcpforge-cli serve --http --port 7331

{
  "mcpServers": {
    "my-api": {
      "url": "http://127.0.0.1:7331/mcp"
    }
  }
}

From source

git clone https://github.com/mpinedaj/mcpforge.git
cd mcpforge
npm install
npm run build
npm test
npm run demo

Features

• OpenAPI 3.x → MCP tools with JSON Schema inputs generated from parameters and request bodies.

• Read-only mode by default, with allowlists and denylists.

• Auth passthrough for bearer tokens, API keys and HTTP basic auth.

• Rate limiting, timeouts and response truncation per tool.

• Audit log in JSONL with automatic secret redaction.

• Two transports: stdio and Streamable HTTP.

• Built-in inspector at / for humans and agents.

• Health endpoint at /health for deployments.

• Zero configuration for the common case.

How it works

OpenAPI 3.x
    │
    ▼
@mcpforge/core ──► mcpforge.json (tool manifest)
                        │
          ┌─────────────┴─────────────┐
          ▼                           ▼
   stdio transport            Streamable HTTP
          │                     ┌─────┴─────┐
          ▼                     ▼           ▼
    MCP clients              /mcp       inspector

The manifest is a plain JSON file. Commit it if you want reproducible tool definitions, or regenerate it in CI when the upstream spec changes.

Security model

MCPForge is a proxy, not a sandbox. Run it with the least-privileged upstream credentials you can, keep readOnly enabled for exploration, and review the allowlist before exposing write operations to an autonomous agent.

Configuration

mcpforge.config.json:

{
  "name": "my-api",
  "version": "0.1.0",
  "manifest": "mcpforge.json",
  "baseUrl": "https://api.example.com",
  "transport": "stdio",
  "http": { "host": "127.0.0.1", "port": 7331 },
  "auth": { "type": "bearer", "tokenEnv": "MY_API_TOKEN" },
  "security": {
    "readOnly": true,
    "allowlist": [],
    "denylist": [],
    "rateLimitPerMinute": 60,
    "timeoutMs": 30000,
    "maxResponseBytes": 1048576,
    "audit": { "enabled": true, "path": ".mcpforge/audit.log" }
  },
  "headers": { "x-client": "mcpforge" }
}

Supported auth types:

{ "type": "none" }
{ "type": "bearer", "tokenEnv": "MY_API_TOKEN" }
{ "type": "apiKey", "in": "header", "name": "X-API-Key", "valueEnv": "MY_API_KEY" }
{ "type": "basic", "username": "me", "passwordEnv": "MY_API_PASSWORD" }

Environment variables

CLI

mcpforge init [spec]       Create a config, import a spec and print next steps
mcpforge generate <spec>   Compile OpenAPI into mcpforge.json
mcpforge serve             Run over stdio (default) or HTTP
mcpforge inspect           Start HTTP and open the inspector
mcpforge build             Create a deployable folder with a Dockerfile

Useful flags:

mcpforge generate ./openapi.yaml \
  --include-tag pets \
  --exclude-operation deletePet \
  --base-url https://staging.example.com

mcpforge serve --http --host 0.0.0.0 --port 7331
mcpforge inspect --no-open --port 7444

Supported sources

Works with

Claude Desktop · Cursor · VS Code (GitHub Copilot MCP) · Windsurf · Cline · any MCP-compatible client.

Examples

• examples/petstore.yaml — the demo spec used by npm run demo.

• Run npm run demo to generate a manifest, start the inspector and call the public Swagger Petstore API.

Roadmap

• v0.1 — MVP (current): OpenAPI import, stdio + HTTP, inspector, read-only mode, allowlists, rate limits, audit log.

• v0.2: GraphQL SDL and read-only PostgreSQL adapters, per-tool scopes, SQLite audit backend, published Docker image.

• v0.3: React/Vite inspector, OAuth2 client credentials, richer OpenAPI 3.1 support, tool output schemas.

• v1.0: Plugin API, policy DSL, hosted tool registry, team audit export.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md, open an issue, or pick a good first issue.

npm install
npm run build
npm run typecheck
npm test

The monorepo layout:

packages/
  shared/      Types, Zod schemas and config parsing
  core/        OpenAPI → tool manifest compiler
  runtime/     Executor, security, audit, MCP transports
  inspector/   Zero-build inspector UI
  cli/         mcpforge command line interface

Security

Please report vulnerabilities privately as described in SECURITY.md. Do not open a public issue for security bugs.

License

MIT © MCPForge contributors

MCPForge is an early-stage MVP. The manifest format and CLI flags may change before v1.0. Pin a version in production.