Master MCP Server
Master MCP Server aggregates multiple MCP servers behind a single, secure endpoint. It provides configuration-driven module loading, unified capability discovery, request routing with resilience, and first-class OAuth flows for multi-backend authentication.
Highlights
- Aggregates multiple MCP servers with tool/resource discovery and namespacing
- OAuth support: master token pass-through, delegated provider flows, proxy refresh
- Config-driven setup with JSON/YAML, schema validation, and secret resolution
- Resilient routing: load-balancing, retries with backoff/jitter, circuit-breakers
- Cross-platform: Node.js server and Cloudflare Workers runtime
- Production-ready deployment: Docker, Cloudflare Workers, Koyeb
- Testing strategy and CI-ready structure
Quick Start (Node.js)
- Install dependencies (requires network):
npm ci
- Configure environment (copy and edit):
cp .env.example .env
- Run in dev mode:
npm run dev
- Health and Metrics:
GET /health→{ ok: true }GET /metrics→ basic system metrics
- MCP endpoints (HTTP gateway):
POST /mcp/tools/listPOST /mcp/tools/callwith{ name, arguments }POST /mcp/resources/listPOST /mcp/resources/readwith{ uri }
See docs/ for full guides and end-to-end examples.
Documentation
- Docs index:
docs/index.md - Getting started:
docs/getting-started/overview.md - Guides:
docs/guides/* - API reference: generated into
docs/api/reference/(see below) - Configuration reference:
docs/configuration/* - Deployment:
docs/deployment/* - Troubleshooting:
docs/troubleshooting/* - Contributing:
docs/contributing/*
Generate API Docs
We use TypeDoc (Markdown) to generate API docs from TypeScript.
- Install (requires network):
npm i -D typedoc typedoc-plugin-markdown
- Generate docs:
npm run docs:api
Outputs to docs/api/.
Examples
Working examples live in examples/:
- Basic Node:
examples/basic-node - Cloudflare Worker:
examples/cloudflare-worker - Advanced Routing:
examples/advanced-routing - OAuth Delegation:
examples/oauth-delegation - Testing Patterns: see
/testsanddocs/examples/testing.md
Each example has a README with run instructions.
Deployment
- Docker:
deploy/docker/*and top-levelDockerfile/docker-compose.yml - Cloudflare Workers:
deploy/cloudflare/*withwrangler.toml - Koyeb:
deploy/koyeb/koyeb.yaml - CI/CD examples: see
docs/deployment/cicd.md
Architecture
Contributing & Support
- See
docs/contributing/*for development workflow and guidelines - See
docs/troubleshooting/index.mdfor solutions - Open an issue or discussion for help and ideas
License
See LICENSE. This repository currently uses UNLICENSED for private/internal use.
