Reference
Architecture Overview - CLI and Cloud Components
System design and component overview for RouterMCP.
Architecture
RouterMCP consists of two main products that share core gateway logic.
Components
┌─────────────────────────────────────────────────────────────┐
│ MCP Clients │
│ (Claude, VS Code, Cursor, Windsurf, etc.) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ RouterMCP Gateway │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ • Tool aggregation and namespacing │ │
│ │ • Request routing to upstream servers │ │
│ │ • Authentication (API keys, OAuth) │ │
│ │ • Filtering (tools, resources, prompts) │ │
│ │ • Code Mode sandbox (optional) │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Upstream MCP Servers │
│ GitHub Linear Notion Filesystem Custom... │
└─────────────────────────────────────────────────────────────┘RouterMCP CLI
The CLI runs locally on your machine:
- Runtime: Node.js
- Transport: Stdio (default) or HTTP
- Configuration:
routermcp.jsoncfile - Process: Single process aggregating multiple upstream servers
RouterMCP Cloud
Cloud is a hosted service:
- API: Cloudflare Workers (Hono)
- Database: Neon Postgres (Drizzle ORM)
- Dashboard: Next.js (Vercel)
- Auth: WorkOS AuthKit
Data Flow
Tool Call Flow
- Client sends
tools/callrequest to RouterMCP - RouterMCP parses tool name to extract server alias
- Request is routed to the appropriate upstream server
- Response is returned to the client
Tool Listing Flow
- Client sends
tools/listrequest - RouterMCP queries all configured upstream servers
- Tools are aggregated with namespace prefixes
- Filtered list is returned based on allow/deny rules
Transport Protocols
| Protocol | Direction | Use Case |
|---|---|---|
| Stdio | Client → Gateway | Local processes (Claude Desktop) |
| HTTP Streamable | Client ↔ Gateway | Remote connections |
| SSE | Client ← Gateway | Streaming responses |
| Stdio | Gateway → Upstream | Local MCP servers |
| HTTP | Gateway → Upstream | Remote MCP servers |
Session Management
In HTTP mode, RouterMCP manages sessions:
- Each client connection gets a unique session
- Sessions maintain state for upstream connections
- Sessions timeout after configurable inactivity
- Multiple clients can connect simultaneously