🌐 OpenAPI-to-MCP Gateway

Enterprise OpenAPI v3 & Swagger to Model Context Protocol (MCP) Gateway
Instantly convert any REST API / OpenAPI spec into production-ready AI Agent Tools.

💡 Why This Project?

Enterprises, banks, and fintech organizations have thousands of established REST APIs, API Gateways (e.g., Axway API Gateway, Kong, Apigee), and national standards (such as BI-SNAP / Open Banking).

However, autonomous AI agents (Claude, Cursor, OpenAI Agents, custom LLMs) communicate via the Model Context Protocol (MCP). Manually wrapping each endpoint into an MCP tool is tedious, error-prone, and unmaintainable.

OpenAPI-to-MCP Gateway acts as a production-grade adapter:

1. Parses any OpenAPI 3.0/3.1 document or Swagger URL.

2. Eliminates Tool Bloat with intelligent Tag & Path Whitelisting so your LLM context window doesn't get flooded.

3. Automates BI-SNAP Cryptographic Signatures (HMAC-SHA512 & ISO timestamps).

4. Trims Large Payloads via built-in FinOps optimizations to save up to 80% on LLM token costs.

5. Provides a Local Web Playground (/playground) alongside Glama MCP Inspector remote SSE support.

Related MCP server: api2mcp

✨ Enterprise & Critical Features

1. 🛡️ Tool Filtering & Anti-Hallucination (Solves Tool Bloat)

Enterprises with hundreds of endpoints risk overflowing the LLM context window. Filter down to only what your AI agent needs:

# Only convert endpoints tagged with "accounts" or "payments"
node dist/index.js --spec api.yaml --tags accounts,payments

# Include only balance and statement endpoints
node dist/index.js --spec api.yaml --include "/v1.0/balance*,/v1.0/statement*"

# Exclude internal / admin paths
node dist/index.js --spec api.yaml --exclude "/internal/*,/admin/*"

2. 🔐 Automated BI-SNAP HMAC-SHA512 Security Hook

Complies with Bank Indonesia National Open Banking API Standard (BI-SNAP). When enabled, every outgoing request is automatically signed with:

• X-TIMESTAMP: ISO 8601 millisecond-precision timestamp.

• X-SIGNATURE: Base64(HMAC-SHA512(Method + ":" + Path + ":" + SHA256(Body) + ":" + Timestamp, SecretKey))

• X-PARTNER-ID, X-EXTERNAL-ID, and CHANNEL-ID.

node dist/index.js --spec samples/bi-snap-banking.yaml --bisnap \
  --bisnap-secret "$BISNAP_SECRET" \
  --bisnap-partner "$BISNAP_PARTNER_ID" \
  --bisnap-channel "$BISNAP_CHANNEL_ID"

3. 💰 FinOps Token Cost Optimization

Large JSON responses (e.g. 100+ transaction rows) can blow up LLM token costs. The gateway automatically:

• Truncates oversized arrays past --max-items (default: 10 items) and inserts truncation notices.

• Strips null and redundant fields.

• Tracks and outputs estimatedTokensSaved per tool call.

4. 📊 Structured Audit Trail & Observability

Every execution emits an audit event for banking compliance:

🟢 [AUDIT] [0c5d7b66] POST /v1.0/balance-inquiry -> SUCCESS (1ms, HTTP 200, MOCK)

5. 🖥️ Built-in Interactive Web Playground (/playground)

Open http://localhost:3000/playground to inspect converted schemas and execute live test calls directly in your browser.

🚀 Quick Start

1. Clone & Install

git clone https://github.com/Hasanromadon/openapi-mcp-gateway.git
cd openapi-mcp-gateway
npm install
npm run build

2. Run with Sample Banking Spec (BI-SNAP)

# Starts gateway on port 3000 in Mock Sandbox Mode with BI-SNAP signing active
npm run demo:banking

3. Run with Corporate Cash Management Spec

npm run demo:cash-management

🌐 Glama Directory and Deployment

This repository includes a glama.json that identifies the GitHub maintainer for Glama. Submit the repository from Glama's MCP servers page while signed in with an account that can write to this repository. Glama builds and inspects open-source servers from their GitHub repository; the Glama Inspector instructions below are for testing a running server and do not submit it to the directory.

The Docker image starts the included BI-SNAP sample in mock mode over Streamable HTTP by default, so it does not call a real banking API. Build and run it locally with:

docker build -t openapi-mcp-gateway .
docker run --rm -p 3000:3000 openapi-mcp-gateway

The Streamable HTTP MCP endpoint is http://localhost:3000/mcp; /health provides a health check. The default /mcp transport is stateless and creates a fresh MCP server per request. The legacy SSE endpoint (/sse and /messages) remains available with --transport sse, and stdio remains available with --transport stdio. The web playground is available in SSE mode at /playground.

Configure deployments with environment variables: SPEC (OpenAPI file path or URL), PORT, TRANSPORT (streamable-http, sse, or stdio), MOCK (true or false), BASE_URL, API_KEY, ALLOWED_UPSTREAM_HOSTS (comma-separated exact hostnames, required when MOCK=false), MCP_AUTH_TOKEN (optional bearer token protecting HTTP MCP and execution routes), BISNAP (true or false), BISNAP_SECRET, BISNAP_PARTNER_ID, and BISNAP_CHANNEL_ID. Enabling BI-SNAP signing requires all three BI-SNAP values; the gateway will not fall back to demo credentials. Command-line options override these defaults. Live mode accepts HTTPS upstreams; plain HTTP is allowed only for localhost development. Redirects from the upstream API are disabled so requests cannot escape the configured host allowlist. HTTP routes are rate-limited to 120 requests per minute per client IP. Store credentials in the deployment's secret manager and avoid putting them in public images or repositories.

Glama's hosted remote connectors require a reachable HTTPS Streamable HTTP endpoint. The local Docker command above exposes HTTP on port 3000; deploy it behind an HTTPS endpoint before submitting it as a hosted connector. Listing this source repository and hosting a remote connector are separate Glama workflows.

🔍 Testing with Glama MCP Inspector

Glama MCP Inspector is the premier browser-based testing environment for MCP servers.

Step-by-Step:

1. Expose your local gateway:

   npx localtunnel --port 3000
   # or
   ngrok http 3000

2. Open Glama Inspector: Navigate to glama.ai/mcp/inspector.

3. Connect: Enter your public SSE URL (e.g., https://your-tunnel.loca.lt/sse) and click Connect.

4. Execute: Test converted tools (getAccountBalance, transferInterbankFunds) and view real-time responses!

💻 Connecting to Claude Desktop / Cursor

Add this gateway to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "banking-gateway": {
      "command": "node",
      "args": [
        "/absolute/path/to/openapi-mcp-gateway/dist/index.js",
        "--spec",
        "/absolute/path/to/openapi-mcp-gateway/samples/bi-snap-banking.yaml",
        "--transport",
        "stdio",
        "--mock"
      ]
    }
  }
}

📂 Included Sample Specifications

👤 Author

Hasan Romadon

• Founder & Product Manager at asesme.com

• LinkedIn: linkedin.com/in/hasanromadon

• GitHub: @Hasanromadon

• Email: hasanromadon@gmail.com

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.