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/list
POST /mcp/tools/call with { name, arguments }
POST /mcp/resources/list
POST /mcp/resources/read with { 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 /tests and docs/examples/testing.md

Each example has a README with run instructions.

Deployment

Docker: deploy/docker/* and top-level Dockerfile / docker-compose.yml
Cloudflare Workers: deploy/cloudflare/* with wrangler.toml
Koyeb: deploy/koyeb/koyeb.yaml
CI/CD examples: see docs/deployment/cicd.md

Architecture

MCP Master Architecture

Contributing & Support

See docs/contributing/* for development workflow and guidelines
See docs/troubleshooting/index.md for solutions
Open an issue or discussion for help and ideas

License

See LICENSE. This repository currently uses UNLICENSED for private/internal use.