MCP Gateway

A Bun-based gateway that brings back the original vision of the web: self-describing, discoverable APIs for AI agents.

Why This Exists

HTTP and HTML were designed as a hypermedia system—clients don't need external documentation because responses contain links describing available actions. REST APIs abandoned this, requiring separate docs for clients to know what endpoints exist.

MCP Gateway restores this pattern for AI agents:

Original Web	MCP Gateway
Browser starts at URL	Agent connects to /mcp
HTML describes available links	Service cards describe available operations
User clicks links to navigate	Agent calls tools/list → tools/call
No external docs needed	No external docs needed

The service card is the modern equivalent of an HTML page with links—a self-describing resource that tells the agent what it can do next.

How It Works

Agent                          Gateway
  │                               │
  ├── tools/list ────────────────►│
  │◄─── [gateway, memory, mesh] ──│
  │                               │
  ├── tools/call memory ──────────►│
  │◄─── "POST /semantic, GET /schema, ..." ──│
  │                               │
  ├── GET /memory/schema ─────────►│  (direct HTTP)
  │◄─── { labels: [...] } ────────│

The agent autonomously explores and understands the API surface, just like a browser exploring a website.

Features

• Self-Describing APIs: Service discovery via MCP protocol (JSON-RPC 2.0)
• OpenAPI-Compatible Config: Define services using familiar OpenAPI structure
• Dynamic Service Loading: Drop TypeScript files in services/ and they're auto-loaded
• STDIO Transport: Connect Claude Code directly via STDIO wrapper
• Zero Dependencies: Pure Bun, no external runtime dependencies

Note: The services/ directory contains example implementations (memory, mesh, recall, orchestrator) that demonstrate the gateway pattern. These are works in progress and require external backends (Neo4j, embedding service). The gateway itself is stable—use it with your own services.

Quick Start

# Clone and install
git clone https://github.com/HiddenDeveloper/mcp-gateway
cd mcp-gateway
bun install

# Start the gateway
bun run src/gateway.ts

Visit http://localhost:3000 to see the gateway landing page.

Usage

MCP Discovery

# List available services
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Get service details
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "memory_service_card"}, "id": 2}'

Direct HTTP Calls

# Call operations directly
curl http://localhost:3000/memory/schema
curl -X POST http://localhost:3000/memory/semantic -d '{"query": "search term"}'

Claude Code Integration

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "my-gateway": {
      "command": "bun",
      "args": ["run", "/path/to/mcp-gateway/src/stdio/wrapper.ts"]
    }
  }
}

The gateway must be running before using the wrapper.

Architecture

                    ┌─────────────────────────────┐
                    │     Bun Gateway (:3000)     │
                    │                             │
MCP Client ────────►│  /mcp  → MCP Handler        │
(HTTP transport)    │         (service discovery) │
                    │                             │
Claude Code ───────►│  STDIO Wrapper ─────────────┼──► /mcp
(STDIO transport)   │  (src/stdio/wrapper.ts)     │
                    │                             │
HTTP Client ───────►│  /{service}/{path}          │
                    │         → Router            │
                    │         → Service Loader    │
                    │         → Service Handler   │
                    └─────────────────────────────┘
                                  │
                                  ▼
                    ┌─────────────────────────────┐
                    │     services/               │
                    │     └── memory/             │
                    │         ├── get_schema.ts   │
                    │         ├── semantic_search │
                    │         ├── text_search.ts  │
                    │         └── execute_cypher  │
                    └─────────────────────────────┘

Configuration

Config File

Create config/gateway.json:

{
  "gateway": {
    "info": { "title": "my-gateway", "version": "1.0.0" },
    "service_card": {
      "operationId": "gateway",
      "summary": "Gateway service discovery"
    }
  },
  "services": [{
    "servers": [{ "url": "http://localhost:3000/memory" }],
    "service_card": {
      "operationId": "memory",
      "summary": "Memory service"
    },
    "paths": {
      "/schema": {
        "get": {
          "operationId": "get_schema",
          "summary": "Get database schema"
        }
      }
    }
  }]
}

Environment Variables

Variable	Default	Description
MCP_CONFIG_PATH	./config/gateway.json	Config file path
MCP_PORT	3000	Server port
MCP_SERVICES_DIR	./services	Services directory
MCP_GATEWAY_URL	http://localhost:3000/mcp	Gateway URL (STDIO wrapper)
MCP_DEBUG	false	Debug logging (STDIO wrapper)

Writing Services

Services are TypeScript files that export a default async function:

// services/memory/semantic_search.ts
import { getNeo4jService } from "./lib/config";

interface Params {
  query: string;
  limit?: number;
  threshold?: number;
}

export default async function(params: Params) {
  const { query, limit = 10, threshold = 0.7 } = params;
  const service = getNeo4jService();

  const results = await service.semanticSearch(query, ["KnowledgeItem"], "embedding_vectors", limit);

  return { matches: results.filter(r => r.score >= threshold) };
}

The gateway:

1. Loads services from services/{serviceId}/{operationId}.ts
2. Routes HTTP requests to the matching service
3. Passes query params, path params, and body as params
4. Returns the service result as JSON

MCP Protocol

Method	Path	Description
GET	/mcp	Server info and capabilities
POST	/mcp	JSON-RPC 2.0 protocol
GET	/health	Health check
GET	/	Landing page

Supported JSON-RPC Methods

• initialize - Initialize MCP connection
• tools/list - List available service cards
• tools/call - Get service details (returns operations)
• ping - Health check

Development

# Run tests
bun test

# Run specific tests
bun test tests/config.test.ts
bun test tests/mcp.test.ts

License

MIT