Stackbilt MCP Gateway

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 with Retry-After and X-RateLimit-* headers
• Cost attribution & quota — every tool call carries a credit cost; quota is reserved via edge-auth before dispatch and committed/refunded on outcome
• Scope enforcement — tools/list is filtered by token scopes; tools/call requires the generate scope 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_ENABLED flag 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