# shashi3070/toolatlas-mcp architecture

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

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

## Overview

ToolAtlas is a control plane for discovering, enriching, governing, and monitoring MCP tools. An operator configures servers and proxy groups in the web UI; the API persists that registry, while the proxy connects to upstream MCP servers, applies per-proxy tool settings, and serves the resulting tools to clients. The UI also exposes glossary management, analytics, testing, and graph views. The graph reflects the sampled wiring and README capabilities; several route and service implementations were not sampled, so their internal links are omitted.

Main entry points: [`src/toolatlas_mcp/api/app.py`](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/app.py) (FastAPI application), [`src/toolatlas_mcp/registry/storage.py`](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/registry/storage.py) (Storage interface), [`ui/src/App.tsx`](https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/App.tsx) (UI routes), [`ui/src/api/client.ts`](https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/api/client.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web console"]
  node_uiapp["UI routes<br/>[App.tsx]"]
  node_uiclient["API client<br/>[client.ts]"]
  node_catalogui["Catalog and dashboard<br/>[Tools.tsx]"]
  node_proxyui["Proxy management<br/>[ProxyDetail.tsx]"]
  node_toolui["Tool detail and testing<br/>[ToolDetail.tsx]"]
  node_glossaryui["Glossary editor<br/>[Glossary.tsx]"]
  node_analyticsui["Analytics and graph<br/>[Graph.tsx]"]
end

subgraph group_api["API and control"]
  node_app["FastAPI application<br/>[app.py]"]
  node_routes["Management routes<br/>[servers.py]"]
  node_toolroutes["Tool routes<br/>[tools.py]"]
  node_proxy_routes["Proxy routes<br/>[proxies.py]"]
  node_graphroutes["Graph routes<br/>[graph.py]"]
  node_analyticsroutes["Analytics routes<br/>[analytics.py]"]
  node_glossaryroutes["Glossary routes<br/>[glossary.py]"]
end

subgraph group_registry["Registry and persistence"]
  node_storage["Storage interface<br/>[storage.py]"]
  node_jsonstore[("JSON registry<br/>[json_storage.py]")]
  node_repository[("SQL registry<br/>[repository.py]")]
  node_db[("Database setup<br/>[db.py]")]
end

subgraph group_runtime["MCP proxy runtime"]
  node_engine["Proxy engine<br/>[engine.py]"]
  node_proxyserver["MCP proxy transport<br/>[server.py]"]
  node_connections["Connection manager"]
  node_mcpwrap["Upstream MCP client<br/>[mcp_client.py]"]
end

subgraph group_ops["Insights and extensions"]
  node_plugins["Plugin hooks<br/>[manager.py]"]
  node_tracker["Call tracking<br/>[service.py]"]
  node_health["Health monitoring<br/>[health_checker.py]"]
  node_sync["Registry synchronization<br/>[registry_sync.py]"]
end

node_operator(("Operator"))
node_mcpclient(("MCP client"))

node_operator -->|"uses"| node_uiapp
node_uiapp -->|"routes to"| node_catalogui
node_uiapp -->|"routes to"| node_proxyui
node_uiapp -->|"routes to"| node_toolui
node_uiapp -->|"routes to"| node_glossaryui
node_uiapp -->|"routes to"| node_analyticsui
node_catalogui -.->|"requests data"| node_uiclient
node_proxyui -->|"manages proxies"| node_uiclient
node_toolui -->|"loads and tests"| node_uiclient
node_glossaryui -->|"manages terms"| node_uiclient
node_analyticsui -.->|"requests insights"| node_uiclient
node_uiclient -.->|"HTTP requests"| node_app
node_app -->|"registers routes"| node_routes
node_app -->|"registers routes"| node_toolroutes
node_app -->|"registers routes"| node_proxy_routes
node_app -->|"registers routes"| node_graphroutes
node_app -->|"registers routes"| node_analyticsroutes
node_app -->|"registers routes"| node_glossaryroutes
node_routes -.->|"reads and writes"| node_storage
node_toolroutes -.->|"reads and writes"| node_storage
node_proxy_routes -.->|"reads configuration"| node_storage
node_graphroutes -.->|"builds topology"| node_storage
node_analyticsroutes -.->|"queries usage"| node_tracker
node_glossaryroutes -.->|"manages glossary"| node_storage
node_jsonstore -->|"implements"| node_storage
node_repository -->|"implements"| node_storage
node_repository -.->|"uses session"| node_db
node_proxyserver -->|"dispatches calls"| node_engine
node_engine -->|"loads proxy settings"| node_storage
node_engine -->|"gets MCP clients"| node_connections
node_connections -->|"connects and initializes"| node_mcpwrap
node_mcpclient -->|"sends MCP requests"| node_proxyserver
node_engine -->|"runs hooks"| node_plugins
node_connections -->|"notifies connection"| node_plugins
node_proxyserver -.->|"records calls"| node_tracker
node_app -.->|"starts monitor"| node_health
node_app -.->|"starts sync"| node_sync

click node_uiapp "https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/App.tsx"
click node_uiclient "https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/api/client.ts"
click node_catalogui "https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/pages/Tools.tsx"
click node_proxyui "https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/pages/ProxyDetail.tsx"
click node_toolui "https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/pages/ToolDetail.tsx"
click node_glossaryui "https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/pages/Glossary.tsx"
click node_analyticsui "https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/pages/Graph.tsx"
click node_app "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/app.py"
click node_routes "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/servers.py"
click node_toolroutes "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/tools.py"
click node_proxy_routes "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/proxies.py"
click node_graphroutes "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/graph.py"
click node_analyticsroutes "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/analytics.py"
click node_glossaryroutes "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/glossary.py"
click node_storage "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/registry/storage.py"
click node_jsonstore "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/registry/json_storage.py"
click node_repository "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/registry/repository.py"
click node_db "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/db.py"
click node_engine "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/proxy/engine.py"
click node_proxyserver "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/proxy/server.py"
click node_connections "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/services/connection_manager.py"
click node_mcpwrap "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/registry/mcp_client.py"
click node_plugins "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/plugin/manager.py"
click node_tracker "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/tracker/service.py"
click node_health "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/services/health_checker.py"
click node_sync "https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/services/registry_sync.py"

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_uiapp,node_uiclient,node_catalogui,node_proxyui,node_toolui,node_glossaryui,node_analyticsui,node_mcpclient toneBlue
class node_app,node_routes,node_toolroutes,node_proxy_routes,node_graphroutes,node_analyticsroutes,node_glossaryroutes toneAmber
class node_storage,node_jsonstore,node_repository,node_db toneMint
class node_engine,node_proxyserver,node_connections,node_mcpwrap toneRose
class node_plugins,node_tracker,node_health,node_sync,node_operator toneIndigo
```

## Components

### Web console

- [UI routes](https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/App.tsx): `ui/src/App.tsx`
- [API client](https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/api/client.ts): `ui/src/api/client.ts`
- [Catalog and dashboard](https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/pages/Tools.tsx): `ui/src/pages/Tools.tsx`
- [Proxy management](https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/pages/ProxyDetail.tsx): `ui/src/pages/ProxyDetail.tsx`
- [Tool detail and testing](https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/pages/ToolDetail.tsx): `ui/src/pages/ToolDetail.tsx`
- [Glossary editor](https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/pages/Glossary.tsx): `ui/src/pages/Glossary.tsx`
- [Analytics and graph](https://github.com/shashi3070/toolatlas-mcp/blob/main/ui/src/pages/Graph.tsx): `ui/src/pages/Graph.tsx`

### API and control

- [FastAPI application](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/app.py): `src/toolatlas_mcp/api/app.py`
- [Management routes](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/servers.py): `src/toolatlas_mcp/api/routes/servers.py`
- [Tool routes](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/tools.py): `src/toolatlas_mcp/api/routes/tools.py`
- [Proxy routes](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/proxies.py): `src/toolatlas_mcp/api/routes/proxies.py`
- [Graph routes](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/graph.py): `src/toolatlas_mcp/api/routes/graph.py`
- [Analytics routes](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/analytics.py): `src/toolatlas_mcp/api/routes/analytics.py`
- [Glossary routes](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/api/routes/glossary.py): `src/toolatlas_mcp/api/routes/glossary.py`

### Registry and persistence

- [Storage interface](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/registry/storage.py): `src/toolatlas_mcp/registry/storage.py`
- [JSON registry](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/registry/json_storage.py): `src/toolatlas_mcp/registry/json_storage.py`
- [SQL registry](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/registry/repository.py): `src/toolatlas_mcp/registry/repository.py`
- [Database setup](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/db.py): `src/toolatlas_mcp/db.py`

### MCP proxy runtime

- [Proxy engine](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/proxy/engine.py): `src/toolatlas_mcp/proxy/engine.py`
- [MCP proxy transport](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/proxy/server.py): `src/toolatlas_mcp/proxy/server.py`
- [Connection manager](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/services/connection_manager.py): `src/toolatlas_mcp/services/connection_manager.py`
- [Upstream MCP client](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/registry/mcp_client.py): `src/toolatlas_mcp/registry/mcp_client.py`

### Insights and extensions

- [Plugin hooks](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/plugin/manager.py): `src/toolatlas_mcp/plugin/manager.py`
- [Call tracking](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/tracker/service.py): `src/toolatlas_mcp/tracker/service.py`
- [Health monitoring](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/services/health_checker.py): `src/toolatlas_mcp/services/health_checker.py`
- [Registry synchronization](https://github.com/shashi3070/toolatlas-mcp/blob/main/src/toolatlas_mcp/services/registry_sync.py): `src/toolatlas_mcp/services/registry_sync.py`

### Other components

- **Operator**
- **MCP client**

## Connections

- Operator → UI routes: uses
- UI routes → Catalog and dashboard: routes to (evidence: `ui/src/App.tsx`)
- UI routes → Proxy management: routes to (evidence: `ui/src/App.tsx`)
- UI routes → Tool detail and testing: routes to (evidence: `ui/src/App.tsx`)
- UI routes → Glossary editor: routes to (evidence: `ui/src/App.tsx`)
- UI routes → Analytics and graph: routes to (evidence: `ui/src/App.tsx`)
- Catalog and dashboard → API client: requests data
- Proxy management → API client: manages proxies (evidence: `ui/src/api/client.ts`)
- Tool detail and testing → API client: loads and tests (evidence: `ui/src/pages/ToolDetail.tsx`)
- Glossary editor → API client: manages terms (evidence: `ui/src/pages/Glossary.tsx`)
- Analytics and graph → API client: requests insights
- API client → FastAPI application: HTTP requests
- FastAPI application → Management routes: registers routes (evidence: `src/toolatlas_mcp/api/app.py`)
- FastAPI application → Tool routes: registers routes (evidence: `src/toolatlas_mcp/api/app.py`)
- FastAPI application → Proxy routes: registers routes (evidence: `src/toolatlas_mcp/api/app.py`)
- FastAPI application → Graph routes: registers routes (evidence: `src/toolatlas_mcp/api/app.py`)
- FastAPI application → Analytics routes: registers routes (evidence: `src/toolatlas_mcp/api/app.py`)
- FastAPI application → Glossary routes: registers routes (evidence: `src/toolatlas_mcp/api/app.py`)
- Management routes → Storage interface: reads and writes
- Tool routes → Storage interface: reads and writes
- Proxy routes → Storage interface: reads configuration
- Graph routes → Storage interface: builds topology
- Analytics routes → Call tracking: queries usage
- Glossary routes → Storage interface: manages glossary
- JSON registry → Storage interface: implements (evidence: `src/toolatlas_mcp/registry/json_storage.py`)
- SQL registry → Storage interface: implements (evidence: `src/toolatlas_mcp/registry/repository.py`)
- SQL registry → Database setup: uses session
- MCP proxy transport → Proxy engine: dispatches calls (evidence: `src/toolatlas_mcp/proxy/server.py`)
- Proxy engine → Storage interface: loads proxy settings (evidence: `src/toolatlas_mcp/proxy/engine.py`)
- Proxy engine → Connection manager: gets MCP clients (evidence: `src/toolatlas_mcp/proxy/engine.py`)
- Connection manager → Upstream MCP client: connects and initializes (evidence: `src/toolatlas_mcp/services/connection_manager.py`)
- MCP client → MCP proxy transport: sends MCP requests
- Proxy engine → Plugin hooks: runs hooks (evidence: `src/toolatlas_mcp/proxy/engine.py`)
- Connection manager → Plugin hooks: notifies connection (evidence: `src/toolatlas_mcp/services/connection_manager.py`)
- MCP proxy transport → Call tracking: records calls
- FastAPI application → Health monitoring: starts monitor (evidence: `src/toolatlas_mcp/api/app.py`)
- FastAPI application → Registry synchronization: starts sync (evidence: `src/toolatlas_mcp/api/app.py`)