Architecture Overview

MCP Director is designed as a high-performance asynchronous proxy-aggregator for the MCP protocol.

System Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Desktop │     │   Claude Code   │     │     Cursor      │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │ STDIO                 │ STDIO                 │ HTTP/SSE
         │                       │                       │
         └───────────────────────┴───────────────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │      MCP Director       │
                    │  ┌───────────────────┐  │
                    │  │  Router + ACL     │  │
                    │  │  Profiles/Projects│  │
                    │  │  Analytics        │  │
                    │  └───────────────────┘  │
                    └────────────┬────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  MCP Server 1   │     │  MCP Server 2   │     │  MCP Server N   │
│   (filesystem)  │     │    (github)     │     │     (custom)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘

Workspace Components

Crates

Crate	Description
mcp-director-protocol	Common data types, wrappers over rmcp, and naming strategies
mcp-director-shared	Common error types, logging utilities, and internationalization
mcp-director-backends	Client-side implementation for connecting to MCP servers (Subprocess, HTTP)
mcp-director-transport	Server-side for receiving connections from AI clients (STDIO, Axum HTTP)
mcp-director-core	Heart of the system: Registry, Request Router, ACL, project/profile managers
mcp-director-config	Configuration loading, SQLite integration, file change tracking

Apps

App	Description
mcp-director-cli	Command-line interface for running and management
mcp-director-web	Web interface based on SvelteKit for management and monitoring

Data Flow

1. Initialization

1. Configuration is loaded
2. Configured backends (servers) are started
3. Tools/resources are polled from each server and registered in the Registry using NamespaceStrategy

2. Request Processing

1. Request arrives via Transport (STDIO or HTTP)
2. Router receives the JSON-RPC request
3. For tools/list: router returns aggregated list from Registry, filtered through profile's AccessControl
4. For tools/call: router resolves namespaced name (e.g., fs/read) into (server=fs, name=read), checks permissions, forwards to Backend
5. Response from backend is returned to client
6. Entire cycle is logged in Analytics (SQLite)

Deployment Modes

Single Client Mode (serve)

Each AI client runs its own MCP Director instance. Simple setup but resources are not shared.

┌─────────────┐     stdio     ┌─────────────────────┐
│ Claude      │◄─────────────►│ mcp-director serve  │
│ Desktop     │               │ (HTTP + Web + STDIO)│
└─────────────┘               └─────────────────────┘

Multi-Client Mode (serve --no-stdio + connect)

One MCP Director daemon serves multiple AI clients. Backends, Web UI, and analytics are shared.

┌─────────────────────────────────────────────────────────────────┐
│                    mcp-director serve --no-stdio                │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────────┐   │
│  │ HTTP :3000    │  │ Router        │  │ Web UI            │   │
│  │  - /mcp       │  │ Registry      │  │ (single instance) │   │
│  │  - /sse       │  │ Backends      │  │                   │   │
│  │  - /api       │  │ Database      │  │                   │   │
│  └───────────────┘  └───────────────┘  └───────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                               ▲
                               │ HTTP POST /mcp
         ┌─────────────────────┼─────────────────────┐
         │                     │                     │
         ▼                     ▼                     ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ mcp-director    │  │ mcp-director    │  │ mcp-director    │
│ connect         │  │ connect         │  │ connect         │
│ (Claude)        │  │ (Cursor)        │  │ (Claude Code)   │
│ stdin ↔ HTTP    │  │ stdin ↔ HTTP    │  │ stdin ↔ HTTP    │
└─────────────────┘  └─────────────────┘  └─────────────────┘

The connect command is a lightweight stdio-to-HTTP bridge that:

1. Reads JSON-RPC messages from stdin
2. Forwards them to the daemon via HTTP POST to /mcp
3. Receives responses and writes them to stdout
4. Maintains session via MCP-Session-Id header

Technologies

Technology	Purpose
Tokio	Asynchronous runtime
Axum	HTTP server for SSE and REST API
SQLx	Working with SQLite for cache and analytics
DashMap	High-performance concurrent collections
SvelteKit	Web UI framework