@bwb03/mcp-gateway

mcp-gateway

Use any MCP server from any agent framework — over plain HTTP.

mcp-gateway is a generic bridge that connects to any MCP server (stdio subprocess or remote HTTP) and exposes its tools as REST endpoints. Configure once with YAML, and any agent — OpenAI Assistants, custom code, OpenClaw, your own Python script — can use MCP servers without speaking the MCP protocol.

┌─────────────┐         ┌──────────────┐         ┌──────────────────┐
│  Any Agent  │  HTTP   │ mcp-gateway  │  MCP    │   MCP Server     │
│  Framework  │ ──────► │              │ ──────► │ (stdio or HTTP)  │
└─────────────┘  REST   └──────────────┘  proto  └──────────────────┘

Why?

The Model Context Protocol is a great way to expose tools to AI agents — but right now it's mostly used inside Claude apps (Desktop, Code, Managed Agents). If you're building with anything else (OpenAI, LangChain, custom frameworks, your own bot), you have to either:

• Hand-code an HTTP wrapper for every MCP server you want to use, or
• Implement the MCP protocol yourself in your agent framework

This gateway does #1 generically. Add a server to a YAML file → its tools become HTTP endpoints. No custom code per provider.

What It Does

• Wraps any MCP server — stdio (subprocess) or HTTP (remote) transport
• Auto-discovers tools — calls listTools() and dynamically generates REST endpoints
• Auto-generates /manifest — agents can introspect available tools and their input schemas
• Handles auth — OAuth 2.1 + PKCE with token persistence, API keys, or no-auth
• Multi-server — run many MCP servers behind one gateway, each on its own port
• Zero hand-coding — same gateway binary works with Filesystem, GitHub, Intentwise, Pacvue, anything

Quick Start

git clone [e-mail]:BWB03/mcp-gateway.git
cd mcp-gateway
npm install
cp gateway.config.example.yaml gateway.config.yaml
npm start

That's it. Out of the box this wraps the Filesystem MCP server (pointed at $HOME) and exposes its 14 tools at http://localhost:3045. Try it:

curl http://localhost:3045/health
curl http://localhost:3045/manifest

Then edit gateway.config.yaml to add more servers — see the example file for templates covering stdio, OAuth, API key, and no-auth servers.

Demo: Two Servers, Side By Side

A single config file wraps a stdio MCP server (Filesystem) and a remote HTTP MCP server (Intentwise) at the same time. Each gets its own port. Each becomes pure HTTP.

gateway.config.yaml:

servers:
  filesystem:
    transport: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/Users/me/projects"
    port: 3045

  intentwise:
    transport: http
    url: https://mcp.intentwise.com/mcp
    port: 3033
    auth:
      type: oauth
      client_id: "your-client-id"
      redirect_uri: "https://your-callback.example.com/callback"

Start the gateway:

$ npm run authorize intentwise   # one-time OAuth
$ npm start

[intentwise] listening on http://localhost:3033
[intentwise] discovered 5 tool(s):
  POST /get_organization        — Returns the list of Intentwise organizations...
  POST /get_intentwise_accounts — Returns the list of AMS accounts for a given organization...
  POST /search_schema           — Search Intentwise schema for relevant tables...
  POST /get_insights            — Generate and execute a BigQuery SQL query from natural language...
  POST /query                   — Generate and execute a BigQuery SQL query (deprecated alias)...

[filesystem] listening on http://localhost:3045
[filesystem] discovered 14 tool(s):
  POST /read_file               — Read the complete contents of a file as text...
  POST /write_file              — Create a new file or completely overwrite an existing file...
  POST /edit_file               — Make line-based edits to a text file...
  POST /list_directory          — Get a detailed listing of all files and directories...
  POST /search_files            — Recursively search for files and directories matching a pattern...
  POST /get_file_info           — Retrieve detailed metadata about a file or directory...
  ... and 8 more

Use it from anywhere — any language, any framework, any agent:

# stdio MCP server (Filesystem)
$ curl -X POST http://localhost:3045/list_directory \
    -H "Content-Type: application/json" \
    -d '{"path":"/Users/me/projects/mcp-gateway/src"}'

"[DIR] auth\n[FILE] config.ts\n[FILE] constants.ts\n[FILE] gateway.ts\n[FILE] index.ts\n[FILE] server.ts"

# Remote HTTP MCP server (Intentwise — OAuth-authenticated)
$ curl -X POST http://localhost:3033/get_organization \
    -H "Content-Type: application/json" \
    -d '{}'

{
  "organizations": [
    { "organization_id": 42280, "name": "Voartex" }
  ]
}

# Health check
$ curl http://localhost:3045/health

{"status":"ok","server":"filesystem","connected":true,"tool_count":14}

# Tool discovery — agents can introspect everything
$ curl http://localhost:3033/manifest

{
  "name": "mcp-gateway:intentwise",
  "version": "0.1.0",
  "transport": "http",
  "upstream": "https://mcp.intentwise.com/mcp",
  "tools": [
    {
      "name": "get_organization",
      "method": "POST",
      "path": "/get_organization",
      "description": "Returns the list of Intentwise organizations...",
      "input_schema": { "type": "object", "properties": { ... } }
    },
    ...
  ]
}

That's the whole story: one YAML, two MCP servers (one local subprocess, one remote OAuth), every tool available as a plain HTTP endpoint. No custom code per provider.

Endpoints (per server)

Each configured server gets its own port and exposes:

Endpoint	Method	Description
/manifest	GET	All discovered tools with their input schemas
/health	GET	Connection status + tool count
/{tool_name}	POST	One endpoint per discovered tool — JSON body matches the tool's input schema

Example: /manifest response

{
  "name": "mcp-gateway:intentwise",
  "version": "0.1.0",
  "transport": "http",
  "upstream": "https://mcp.intentwise.com/mcp",
  "base_url": "http://localhost:3033",
  "tools": [
    {
      "name": "get_organization",
      "method": "POST",
      "path": "/get_organization",
      "description": "Returns the list of Intentwise organizations...",
      "input_schema": {
        "type": "object",
        "properties": {
          "name_filter": { "type": "string" }
        }
      }
    }
  ]
}

Agents can hit /manifest once to learn everything about what's available.

CLI

mcp-gateway                  # Start all servers from gateway.config.yaml
mcp-gateway start <server>   # Start a specific server
mcp-gateway tools <server>   # List discovered tools for a server (no HTTP listener)
mcp-gateway status           # Show all configured servers
mcp-gateway --version
mcp-gateway --help

OAuth setup (one-time per HTTP server with auth.type: oauth):

npm run authorize <server_name>

Configuration Reference

Common fields

Field	Required	Description
transport	✅	"http" or "stdio"
port	✅	Local port the gateway listens on for this server
path_prefix	optional	URL prefix for all tool paths (e.g., intentwise → /intentwise/get_organization)

transport: http fields

Field	Required	Description
url	✅	Remote MCP server URL
auth	✅	Auth config (oauth / api_key / none)

transport: stdio fields

Field	Required	Description
command	✅	Executable to run (e.g., npx, node, python)
args	optional	Command-line arguments
env	optional	Environment variables for the subprocess (${VAR} expanded from process.env)
cwd	optional	Working directory for the subprocess

Auth types (for HTTP transport)

# OAuth 2.1 with PKCE
auth:
  type: oauth
  client_id: "..."
  redirect_uri: "https://..."
  scope: "..."          # optional
  token_file: "..."     # optional, defaults to ~/.mcp-gateway/tokens/{server}.json

# API key in header
auth:
  type: api_key
  header: X-API-Key
  env: MY_API_KEY       # value pulled from process.env at startup

# Public / no auth
auth:
  type: none

How It Compares

	mcp-gateway	Hand-coded HTTP adapter	Claude Managed Agents
Works with non-Claude agents	✅	✅	❌
Self-hosted	✅	✅	❌ Anthropic only
stdio MCP support	✅	One-off code	✅
Remote HTTP MCP support	✅	One-off code	✅
Multi-server in one process	✅	❌ Build it	✅
Auto-discovers tools	✅	❌ Hand-coded	✅
Auto-generated manifests	✅	❌ Hand-coded	N/A (native tool calls)
Effort to add a new MCP server	YAML entry	Days of code	Add to agent config
Cost	Free (your infra)	Free	Per session-hour + tokens

Use Claude Managed Agents if your agents are Claude-based and you want zero infrastructure. Use mcp-gateway if you're using OpenAI / LangChain / custom frameworks, need self-hosting, or want a drop-in HTTP layer for any MCP server.

Architecture

mcp-gateway/
  src/
    index.ts              # CLI entry — reads config, starts gateways
    config.ts             # YAML parser + Zod validation + ${ENV} expansion
    gateway.ts            # Core: MCP client wrapper + transport selection + discovery
    server.ts             # HTTP server with dynamic routes per discovered tool
    auth/
      oauth-provider.ts   # Generic OAuth 2.1 + PKCE implementation
  scripts/
    authorize.ts          # Browser-based OAuth bootstrap
  gateway.config.yaml     # Your server definitions (gitignored)

How a tool call flows

1. Agent: POST http://localhost:3033/get_organization { }
2. Gateway: routes path to upstream tool name "get_organization"
3. Gateway → MCP Client → Upstream MCP Server: callTool("get_organization", {})
4. Upstream returns MCP CallToolResult with text content
5. Gateway extracts text, parses as JSON
6. Agent receives plain JSON response

The gateway is a thin proxy. It doesn't transform, cache, or rate-limit by default — those are planned as optional middleware.

Roadmap

• Phase 1: Core gateway — config, discovery, dynamic routes, manifest, OAuth
• Phase 1.5: stdio support — wrap any subprocess MCP server
• Phase 2: Multi-server validation — battle-test with 5+ different MCP servers
• Phase 3: Middleware — universal envelope wrapper, response cache, rate limiting, structured logging
• Phase 4: Hosted mode — Docker + Railway deployment, multi-tenant token storage

See the project plan for details.

Development

npm install
npm run dev          # Run via tsx
npm run build        # Build with tsup
npm test             # Unit tests (vitest)

Project uses native node:http (no Express/Fastify), @modelcontextprotocol/sdk for MCP, zod for validation, and yaml for config parsing.

Contributing

Contributions welcome. See CONTRIBUTING.md. For security issues, see SECURITY.md.

License

MIT — see LICENSE.