# super-mcp

**Multiple MCP servers put together as one.** A gateway that spawns each configured sub-MCP, namespaces and re-exposes all of their tools, and forwards calls — so the agent connects to *one* MCP and gets the whole stack.

```
                         ┌────────────── super-mcp (gateway) ──────────────┐
   Claude  ── stdio ──▶  │  tools/list  ─▶  cloudflare__list_zones          │
                         │                  owndomain__own_domain_fanout    │
                         │                  godaddy__list_domains  ...       │
                         │  tools/call  ─▶  route by prefix ─▶ sub-MCP       │
                         └───────┬───────────────┬───────────────┬──────────┘
                          stdio  │        stdio  │        stdio  │
                          cloudflare-mcp   own-domain-mcp   godaddy-mcp
                                 └─────────────── each → its vendor REST API
```

## Why this (and why MCP → API all the way down)

Every sub-server is itself an MCP wrapping a **direct vendor REST API** (Cloudflare, GoDaddy, …). The gateway changes nothing about that contract — it just unifies the surface. So the full path stays **MCP → API**: deterministic, least-privilege, no browser. The namespace prefix (`cloudflare__`, `owndomain__`, `godaddy__`) keeps it explicit which underlying API served any call, even through the aggregator.

Benefits:

- **One connection, whole stack.** Register `super-mcp` once instead of N servers.
- **Add by config.** Drop a server into `config/servers.json` (or `SUPER_MCP_SERVERS`); no code change.
- **Decoupled.** Sub-servers run as their own processes with their own scoped creds; a crash in one doesn't take down the rest (it's skipped with a logged error).

## Config

`config/servers.json`:

```json
{
  "servers": [
    { "name": "cloudflare", "command": "node", "args": ["/path/to/cloudflare-mcp/dist/index.js"] },
    { "name": "owndomain",  "command": "node", "args": ["/path/to/own-domain-mcp/dist/index.js"] },
    { "name": "godaddy",    "command": "node", "args": ["/path/to/godaddy-mcp/dist/index.js"] }
  ]
}
```

Override with `SUPER_MCP_SERVERS` (a path to a JSON file, or inline JSON). Per-server `env` is merged over the parent environment.

## Install

```bash
npm install && npm run build
# build the sub-servers too (they must have dist/ outputs)
claude mcp add super -- node ~/code/personal/super-mcp/dist/index.js
npm test
```

## Notes

- Tools are advertised with their **original JSON Schema** passed straight through — no re-validation, no lossy Zod round-trip.
- The gateway is a low-level MCP `Server`; it answers `tools/list` and `tools/call` only. Sub-server prompts/resources are intentionally not aggregated (tools are the surface families share).