# avelino/mcp architecture

> Architecture diagram of the GitHub repository avelino/mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/avelino/mcp
- Repository: https://github.com/avelino/mcp

## Overview

mcp is a Rust CLI for invoking MCP tools and exposing configured backends through a unified proxy. In the direct workflow, a terminal command is routed through the CLI, configuration selects a backend, the client speaks JSON-RPC over a supported transport, and the result is rendered as JSON. Proxy mode adds backend discovery, lazy/shared connections, dispatch, and access control. The README documents registry management, CLI wrapping, OAuth, reload, audit, and telemetry; some of these paths are represented at their documented subsystem level because their implementation was not sampled.

Main entry points: [`src/main.rs`](https://github.com/avelino/mcp/blob/main/src/main.rs) (Command router), [`src/serve/dispatch.rs`](https://github.com/avelino/mcp/blob/main/src/serve/dispatch.rs) (Request dispatch), [`src/client.rs`](https://github.com/avelino/mcp/blob/main/src/client.rs) (MCP client), [`src/serve/proxy.rs`](https://github.com/avelino/mcp/blob/main/src/serve/proxy.rs) (Backend lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and configuration"]
  node_main["Command router<br/>[main.rs]"]
  node_config["Server configuration<br/>[config.rs]"]
  node_manager["Server management<br/>[manager.rs]"]
  node_registry["Server registry<br/>[registry.rs]"]
  node_output["JSON output<br/>[output.rs]"]
  node_reload["Live reload<br/>[reload.rs]"]
  node_logs["Audit log command<br/>[logs.rs]"]
end

subgraph group_connect["Backend connections"]
  node_cli_discovery["CLI tool discovery<br/>[cli_discovery.rs]"]
  node_client["MCP client<br/>[client.rs]"]
  node_protocol["JSON-RPC and MCP<br/>[protocol.rs]"]
  node_transport["Transport selection<br/>[which.rs]"]
  node_stdio["Stdio transport<br/>[stdio.rs]"]
  node_http_transport["HTTP transport<br/>[http.rs]"]
  node_cli_transport["CLI backend transport<br/>[cli.rs]"]
end

subgraph group_proxy["Proxy runtime"]
  node_serve["Proxy entrypoints<br/>[http.rs]"]
  node_proxy_core["Backend lifecycle<br/>[proxy.rs]"]
  node_dispatch["Request dispatch<br/>[dispatch.rs]"]
end

subgraph group_security["Authentication and access"]
  node_acl["Access policies<br/>[eval.rs]"]
  node_server_auth["Proxy authentication<br/>[mod.rs]"]
  node_oauth_client["Client OAuth<br/>[oauth.rs]"]
  node_oauth_server["Authorization server<br/>[authorize.rs]"]
end

subgraph group_state["State and observability"]
  node_cache[("Tool cache<br/>[cache.rs]")]
  node_audit["Audit logging<br/>[audit.rs]"]
  node_database[("ChronDB pool<br/>[db.rs]")]
  node_telemetry["OpenTelemetry<br/>[telemetry.rs]"]
end

node_terminal(("Terminal user"))
node_backend{{"MCP backend"}}

node_terminal -->|"runs command"| node_main
node_main -->|"loads config"| node_config
node_main -->|"routes management"| node_manager
node_manager -->|"uses registry"| node_registry
node_main -->|"searches registry"| node_registry
node_main -->|"invokes backend"| node_client
node_client -->|"encodes requests"| node_protocol
node_client -->|"selects transport"| node_transport
node_transport -->|"chooses stdio"| node_stdio
node_transport -->|"chooses HTTP"| node_http_transport
node_transport -->|"chooses CLI"| node_cli_transport
node_cli_transport -->|"discovers commands"| node_cli_discovery
node_stdio -.->|"exchanges messages"| node_backend
node_http_transport -.->|"exchanges messages"| node_backend
node_cli_transport -.->|"runs command"| node_backend
node_client -->|"authenticates when needed"| node_oauth_client
node_main -->|"renders result"| node_output
node_main -->|"starts proxy"| node_serve
node_serve -->|"runs proxy"| node_proxy_core
node_serve -->|"routes requests"| node_dispatch
node_dispatch -->|"dispatches backend calls"| node_proxy_core
node_proxy_core -->|"connects backends"| node_client
node_proxy_core -->|"persists tool cache"| node_cache
node_dispatch -->|"checks permissions"| node_acl
node_dispatch -->|"resolves identity"| node_server_auth
node_server_auth -->|"provides OAuth"| node_oauth_server
node_main -->|"applies reload"| node_reload
node_main -.->|"shows audit logs"| node_logs
node_dispatch -->|"records activity"| node_audit
node_audit -->|"writes entries"| node_database
node_database -->|"gets storage paths"| node_config
node_proxy_core -->|"emits telemetry"| node_telemetry

click node_main "https://github.com/avelino/mcp/blob/main/src/main.rs"
click node_config "https://github.com/avelino/mcp/blob/main/src/config.rs"
click node_manager "https://github.com/avelino/mcp/blob/main/src/manager.rs"
click node_registry "https://github.com/avelino/mcp/blob/main/src/registry.rs"
click node_cli_discovery "https://github.com/avelino/mcp/blob/main/src/cli_discovery.rs"
click node_client "https://github.com/avelino/mcp/blob/main/src/client.rs"
click node_protocol "https://github.com/avelino/mcp/blob/main/src/protocol.rs"
click node_transport "https://github.com/avelino/mcp/blob/main/src/transport/which.rs"
click node_stdio "https://github.com/avelino/mcp/blob/main/src/transport/stdio.rs"
click node_http_transport "https://github.com/avelino/mcp/blob/main/src/transport/http.rs"
click node_cli_transport "https://github.com/avelino/mcp/blob/main/src/transport/cli.rs"
click node_output "https://github.com/avelino/mcp/blob/main/src/output.rs"
click node_serve "https://github.com/avelino/mcp/blob/main/src/serve/http.rs"
click node_proxy_core "https://github.com/avelino/mcp/blob/main/src/serve/proxy.rs"
click node_dispatch "https://github.com/avelino/mcp/blob/main/src/serve/dispatch.rs"
click node_cache "https://github.com/avelino/mcp/blob/main/src/cache.rs"
click node_acl "https://github.com/avelino/mcp/blob/main/src/server_auth/acl/eval.rs"
click node_server_auth "https://github.com/avelino/mcp/blob/main/src/server_auth/mod.rs"
click node_oauth_client "https://github.com/avelino/mcp/blob/main/src/auth/oauth.rs"
click node_oauth_server "https://github.com/avelino/mcp/blob/main/src/server_auth/oauth_as/authorize.rs"
click node_audit "https://github.com/avelino/mcp/blob/main/src/audit.rs"
click node_database "https://github.com/avelino/mcp/blob/main/src/db.rs"
click node_telemetry "https://github.com/avelino/mcp/blob/main/src/telemetry.rs"
click node_reload "https://github.com/avelino/mcp/blob/main/src/cli/reload.rs"
click node_logs "https://github.com/avelino/mcp/blob/main/src/cli/logs.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config,node_manager,node_registry,node_output,node_reload,node_logs,node_terminal toneBlue
class node_cli_discovery,node_client,node_protocol,node_transport,node_stdio,node_http_transport,node_cli_transport toneAmber
class node_serve,node_proxy_core,node_dispatch toneMint
class node_acl,node_server_auth,node_oauth_client,node_oauth_server toneRose
class node_cache,node_audit,node_database,node_telemetry,node_backend toneIndigo
```

## Components

### CLI and configuration

- [Command router](https://github.com/avelino/mcp/blob/main/src/main.rs): `src/main.rs`
- [Server configuration](https://github.com/avelino/mcp/blob/main/src/config.rs): `src/config.rs`
- [Server management](https://github.com/avelino/mcp/blob/main/src/manager.rs): `src/manager.rs`
- [Server registry](https://github.com/avelino/mcp/blob/main/src/registry.rs): `src/registry.rs`
- [JSON output](https://github.com/avelino/mcp/blob/main/src/output.rs): `src/output.rs`
- [Live reload](https://github.com/avelino/mcp/blob/main/src/cli/reload.rs): `src/cli/reload.rs`
- [Audit log command](https://github.com/avelino/mcp/blob/main/src/cli/logs.rs): `src/cli/logs.rs`

### Backend connections

- [CLI tool discovery](https://github.com/avelino/mcp/blob/main/src/cli_discovery.rs): `src/cli_discovery.rs`
- [MCP client](https://github.com/avelino/mcp/blob/main/src/client.rs): `src/client.rs`
- [JSON-RPC and MCP](https://github.com/avelino/mcp/blob/main/src/protocol.rs): `src/protocol.rs`
- [Transport selection](https://github.com/avelino/mcp/blob/main/src/transport/which.rs): `src/transport/which.rs`
- [Stdio transport](https://github.com/avelino/mcp/blob/main/src/transport/stdio.rs): `src/transport/stdio.rs`
- [HTTP transport](https://github.com/avelino/mcp/blob/main/src/transport/http.rs): `src/transport/http.rs`
- [CLI backend transport](https://github.com/avelino/mcp/blob/main/src/transport/cli.rs): `src/transport/cli.rs`

### Proxy runtime

- [Proxy entrypoints](https://github.com/avelino/mcp/blob/main/src/serve/http.rs): `src/serve/http.rs`
- [Backend lifecycle](https://github.com/avelino/mcp/blob/main/src/serve/proxy.rs): `src/serve/proxy.rs`
- [Request dispatch](https://github.com/avelino/mcp/blob/main/src/serve/dispatch.rs): `src/serve/dispatch.rs`

### Authentication and access

- [Access policies](https://github.com/avelino/mcp/blob/main/src/server_auth/acl/eval.rs): `src/server_auth/acl/eval.rs`
- [Proxy authentication](https://github.com/avelino/mcp/blob/main/src/server_auth/mod.rs): `src/server_auth/mod.rs`
- [Client OAuth](https://github.com/avelino/mcp/blob/main/src/auth/oauth.rs): `src/auth/oauth.rs`
- [Authorization server](https://github.com/avelino/mcp/blob/main/src/server_auth/oauth_as/authorize.rs): `src/server_auth/oauth_as/authorize.rs`

### State and observability

- [Tool cache](https://github.com/avelino/mcp/blob/main/src/cache.rs): `src/cache.rs`
- [Audit logging](https://github.com/avelino/mcp/blob/main/src/audit.rs): `src/audit.rs`
- [ChronDB pool](https://github.com/avelino/mcp/blob/main/src/db.rs): `src/db.rs`
- [OpenTelemetry](https://github.com/avelino/mcp/blob/main/src/telemetry.rs): `src/telemetry.rs`

### Other components

- **Terminal user**
- **MCP backend**

## Connections

- Terminal user → Command router: runs command (evidence: `README.md`)
- Command router → Server configuration: loads config (evidence: `src/main.rs`)
- Command router → Server management: routes management (evidence: `src/main.rs`)
- Server management → Server registry: uses registry (evidence: `src/manager.rs`)
- Command router → Server registry: searches registry (evidence: `src/main.rs`)
- Command router → MCP client: invokes backend (evidence: `src/main.rs`)
- MCP client → JSON-RPC and MCP: encodes requests (evidence: `src/client.rs`)
- MCP client → Transport selection: selects transport (evidence: `src/client.rs`)
- Transport selection → Stdio transport: chooses stdio (evidence: `src/transport/mod.rs`)
- Transport selection → HTTP transport: chooses HTTP (evidence: `src/transport/mod.rs`)
- Transport selection → CLI backend transport: chooses CLI (evidence: `src/transport/mod.rs`)
- CLI backend transport → CLI tool discovery: discovers commands (evidence: `src/transport/cli.rs`)
- Stdio transport → MCP backend: exchanges messages (evidence: `README.md`)
- HTTP transport → MCP backend: exchanges messages (evidence: `README.md`)
- CLI backend transport → MCP backend: runs command (evidence: `README.md`)
- MCP client → Client OAuth: authenticates when needed (evidence: `src/client.rs`)
- Command router → JSON output: renders result (evidence: `src/main.rs`)
- Command router → Proxy entrypoints: starts proxy (evidence: `README.md`)
- Proxy entrypoints → Backend lifecycle: runs proxy (evidence: `src/serve/http.rs`)
- Proxy entrypoints → Request dispatch: routes requests (evidence: `src/serve/http.rs`)
- Request dispatch → Backend lifecycle: dispatches backend calls (evidence: `src/serve/dispatch.rs`)
- Backend lifecycle → MCP client: connects backends (evidence: `src/serve/proxy.rs`)
- Backend lifecycle → Tool cache: persists tool cache (evidence: `src/serve/proxy.rs`)
- Request dispatch → Access policies: checks permissions (evidence: `src/serve/dispatch.rs`)
- Request dispatch → Proxy authentication: resolves identity (evidence: `src/serve/dispatch.rs`)
- Proxy authentication → Authorization server: provides OAuth (evidence: `src/server_auth/mod.rs`)
- Command router → Live reload: applies reload (evidence: `src/main.rs`)
- Command router → Audit log command: shows audit logs (evidence: `README.md`)
- Request dispatch → Audit logging: records activity (evidence: `src/serve/dispatch.rs`)
- Audit logging → ChronDB pool: writes entries (evidence: `src/audit.rs`)
- ChronDB pool → Server configuration: gets storage paths (evidence: `src/db.rs`)
- Backend lifecycle → OpenTelemetry: emits telemetry (evidence: `src/serve/proxy.rs`)
