Stackbilt MCP Gateway
<p align="center"> <img src="docs/banner.png" alt="Stackbilt MCP Gateway — Stackbilder" width="480" /> </p>
MCP Registry:
dev.stackbilt.mcp/gateway— published on the Official MCP Registry
OAuth-authenticated Model Context Protocol (MCP) gateway for Stackbilt platform services. Built as a Cloudflare Worker using @cloudflare/workers-oauth-provider.
What It Does
A single MCP endpoint (mcp.stackbilt.dev/mcp) that routes tool calls to multiple backend product workers:
| Backend | Tools | Description |
|---|---|---|
| TarotScript | scaffold_create, scaffold_classify, scaffold_publish, scaffold_deploy, scaffold_import, scaffold_status | Deterministic project scaffolding, n8n workflow import, GitHub publishing, CF deployment |
The Scaffold Pipeline (E2E)
You: "Build a restaurant menu API with D1 storage"
↓
scaffold_create → structured facts + 9 deployable project files
↓
scaffold_publish → GitHub repo with atomic initial commit
↓
git clone → npm install → npx wrangler deploy → live Worker
Zero LLM calls for file generation. ~20ms for structure, ~2s with oracle prose. 21x faster than flow_create.
Key Features
- OAuth 2.1 with PKCE — GitHub SSO, Google SSO, and email/password authentication
- Backend adapter pattern — tool catalogs aggregated from multiple service bindings, namespaced to avoid collisions
- Per-tier rate limiting — fixed-window per-tenant limits via
RATELIMIT_KV(free=20/min, hobby=60, pro=300, enterprise=1000); 429 withRetry-AfterandX-RateLimit-*headers - Cost attribution & quota — every tool call carries a credit cost; quota is reserved via
edge-authbefore dispatch and committed/refunded on outcome - Scope enforcement —
tools/listis filtered by token scopes;tools/callrequires thegeneratescope for mutating tools - Security Constitution compliance — every tool declares a risk level (
READ_ONLY,LOCAL_MUTATION,EXTERNAL_MUTATION); structured audit logging with secret redaction; HMAC-signed identity tokens - Coming-soon gate —
PUBLIC_SIGNUPS_ENABLEDflag to control public access - MCP JSON-RPC over HTTP — supports both streaming (SSE) and request/response transport
Quick Start
Prerequisites
- Node.js 18+
- Wrangler CLI (
npm i -g wrangler) - Cloudflare account with the required service bindings configured
Install & Run
npm install
npm run dev
Run Tests
npm test
Deploy
npm run deploy
Deploys to the mcp.stackbilt.dev custom domain via Cloudflare Workers.
Environment Variables & Secrets
| Name | Type | Description |
|---|---|---|
SERVICE_BINDING_SECRET | Secret | HMAC-SHA256 key for signing identity tokens |
TAROTSCRIPT_API_KEY | Secret | Bearer key for protected TarotScript routes (/run, /classify, /agents/*) |
API_BASE_URL | Variable | Base URL for OAuth redirects (e.g. https://mcp.stackbilt.dev) |
AUTH_SERVICE | Service Binding | RPC to edge-auth worker (AuthEntrypoint) |
TAROTSCRIPT | Service Binding | Route to scaffold + classify backend |
OAUTH_KV | KV Namespace | Stores social OAuth state (5-min TTL entries) and MCP sessions |
RATELIMIT_KV | KV Namespace | Per-tenant fixed-window rate-limit counters (60s TTL) |
PLATFORM_EVENTS_QUEUE | Queue | Audit event pipeline (stackbilt-user-events) |
MCP_REGISTRY_AUTH | Variable | MCP Registry domain verification string (served at /.well-known/mcp-registry-auth) |
Set secrets with:
wrangler secret put SERVICE_BINDING_SECRET
Project Structure
src/
index.ts # Entry point — OAuthProvider setup, CORS, health check, MCP Registry well-known
gateway.ts # MCP JSON-RPC transport, session management, tool dispatch
rest-scaffold.ts # REST scaffold endpoint (POST /api/scaffold) for CLI consumers
oauth-handler.ts # OAuth 2.1 flows: login, signup, social SSO, consent
tool-registry.ts # Tool catalog aggregation, namespacing, schema validation
cost-attribution.ts # Per-tool credit costs and quota feature key mapping
rate-limiter.ts # Fixed-window per-tenant rate limiting via KV
billing-tools.ts # billing_status / billing_purchase_credits MCP tool handlers
audit.ts # Structured audit logging, secret redaction, trace IDs
auth.ts # Bearer token extraction & validation
route-table.ts # Static routing table, tool-to-backend mapping, risk levels
types.ts # Type definitions, RiskLevel enum, GatewayEnv interface
test/
audit.test.ts
auth.test.ts
billing-agent-charge.test.ts
billing-tools.test.ts
cost-attribution.test.ts
gateway.test.ts
index.test.ts
oauth-handler.test.ts
rate-limiter.test.ts
rest-scaffold.test.ts
route-table.test.ts
tool-registry.test.ts
docs/
user-guide.md # End-user guide: account creation, client setup, tool usage
api-reference.md # MCP tool surface, authentication flow, tool routing
architecture.md # System design, security model, request flow
Test Suite
195 tests across 14 test files covering:
- OAuth handler — identity token signing/verification, login, signup, social OAuth flows, consent, HTML escaping
- Gateway — session lifecycle,
initialize,tools/list,tools/call, SSE streaming, error handling - Audit — secret redaction patterns (API keys, bearer tokens, hex hashes, password fields), trace IDs, queue emission
- Auth — bearer token extraction, API key vs JWT validation, error mapping
- Tool registry — catalog building, name mapping, schema validation, risk level enforcement
- Route table — route resolution, risk level lookup
npm test # single run
npm run test:watch # watch mode
Documentation
- User Guide — account creation, client setup, tool usage
- API Reference — MCP tools, authentication, tool routing
- Architecture — system design, security model, data flow
License
MIT — see LICENSE