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.tsVisit 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:
- Loads services from
services/{serviceId}/{operationId}.ts - Routes HTTP requests to the matching service
- Passes query params, path params, and body as
params - 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 connectiontools/list- List available service cardstools/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.tsLicense
MIT
