# tuskira/ai-agent-gateway architecture

> Architecture diagram of the GitHub repository tuskira/ai-agent-gateway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tuskira/ai-agent-gateway
- Repository: https://github.com/tuskira/ai-agent-gateway

## Overview

AI Agent Gateway is a self-hosted gateway for MCP tools and multiple LLM providers. Agents authenticate at the gateway, use profile-scoped MCP tools, prompts, resources, and skills, or make proxied LLM calls; the gateway can inject outbound credentials and capture calls for logs and analytics. Administrators manage tenants, connectors, profiles, keys, models, and users through the REST API and embedded console. The README documents the major capabilities; several internal links below are supported by sampled source, while unsampled integrations are omitted rather than inferred.

Main entry points: [`internal/dataplane/orchestrator/orchestrator.go`](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/dataplane/orchestrator/orchestrator.go) (MCP orchestrator), [`internal/llmplane/router.go`](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/llmplane/router.go) (LLM request router), [`internal/api/router.go`](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/api/router.go) (Control API), [`cmd/gateway/main.go`](https://github.com/tuskira/ai-agent-gateway/blob/main/cmd/gateway/main.go) (Gateway process)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Gateway runtime"]
  node_gateway["Gateway process<br/>[main.go]"]
  node_auth["API key auth<br/>[authenticator.go]"]
end

subgraph group_mcp["MCP access"]
  node_mcp["MCP orchestrator<br/>[orchestrator.go]"]
  node_toolroute["Tool routing<br/>[router.go]"]
  node_mcpclient["Backend MCP client<br/>[client.go]"]
  node_sessions["MCP sessions<br/>[session.go]"]
  node_skills["Skills validation<br/>[validate.go]"]
end

subgraph group_llm["LLM proxy"]
  node_llmrouter["LLM request router<br/>[router.go]"]
  node_translation["Dialect translation<br/>[engine.go]"]
  node_providers{{"LLM providers"}}
  node_discovery["Tool discovery<br/>[discovery.go]"]
end

subgraph group_admin["Administration"]
  node_api["Control API<br/>[router.go]"]
  node_handlers["Admin handlers<br/>[connectors.go]"]
  node_console["Admin console<br/>[App.tsx]"]
end

subgraph group_data["Persistence and analytics"]
  node_pg[("PostgreSQL store<br/>[store.go]")]
  node_ingest["Log ingestion<br/>[ingest.go]"]
  node_analytics[("Analytics sink<br/>[ingest.go]")]
end

node_agent(("Agent client"))
node_connector{{"MCP server"}}
node_provider{{"LLM service"}}

node_agent -->|"authenticates"| node_auth
node_auth -.->|"authorizes"| node_mcp
node_auth -.->|"authorizes"| node_llmrouter
node_agent -->|"calls MCP"| node_mcp
node_mcp -->|"resolves tools"| node_toolroute
node_mcp -->|"dispatches calls"| node_mcpclient
node_mcp -->|"uses sessions"| node_sessions
node_mcp -->|"serves skills"| node_skills
node_mcpclient -->|"sends MCP"| node_connector
node_agent -->|"sends LLM calls"| node_llmrouter
node_llmrouter -->|"translates dialect"| node_translation
node_llmrouter -->|"routes requests"| node_providers
node_providers -->|"calls upstream"| node_provider
node_llmrouter -->|"scans responses"| node_discovery
node_gateway -->|"starts plane"| node_api
node_gateway -->|"starts plane"| node_mcp
node_gateway -.->|"starts plane"| node_llmrouter
node_console -.->|"uses REST"| node_api
node_api -->|"routes requests"| node_handlers
node_handlers -.->|"manages records"| node_pg
node_agent -->|"submits logs"| node_ingest
node_ingest -.->|"writes records"| node_analytics
node_llmrouter -->|"captures calls"| node_analytics
node_api -->|"requires persistence"| node_pg

click node_gateway "https://github.com/tuskira/ai-agent-gateway/blob/main/cmd/gateway/main.go"
click node_auth "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/auth/apikey/authenticator.go"
click node_mcp "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/dataplane/orchestrator/orchestrator.go"
click node_toolroute "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/dataplane/router/router.go"
click node_mcpclient "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/dataplane/client/client.go"
click node_sessions "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/dataplane/session/session.go"
click node_skills "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/skills/validate.go"
click node_llmrouter "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/llmplane/router.go"
click node_translation "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/llmplane/translate/engine.go"
click node_providers "https://github.com/tuskira/ai-agent-gateway/tree/main/internal/llmplane"
click node_api "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/api/router.go"
click node_handlers "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/api/handlers/connectors.go"
click node_console "https://github.com/tuskira/ai-agent-gateway/blob/main/web/src/App.tsx"
click node_pg "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/store/postgres/store.go"
click node_ingest "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/api/handlers/ingest.go"
click node_analytics "https://github.com/tuskira/ai-agent-gateway/blob/main/pkg/sink/clickhouse/ingest.go"
click node_discovery "https://github.com/tuskira/ai-agent-gateway/blob/main/internal/discovery/discovery.go"

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_gateway,node_auth,node_agent toneBlue
class node_mcp,node_toolroute,node_mcpclient,node_sessions,node_skills toneAmber
class node_llmrouter,node_translation,node_providers,node_discovery,node_connector toneMint
class node_api,node_handlers,node_console toneRose
class node_pg,node_ingest,node_analytics,node_provider toneIndigo
```

## Components

### Gateway runtime

- [Gateway process](https://github.com/tuskira/ai-agent-gateway/blob/main/cmd/gateway/main.go): `cmd/gateway/main.go`
- [API key auth](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/auth/apikey/authenticator.go): `internal/auth/apikey/authenticator.go`

### MCP access

- [MCP orchestrator](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/dataplane/orchestrator/orchestrator.go): `internal/dataplane/orchestrator/orchestrator.go`
- [Tool routing](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/dataplane/router/router.go): `internal/dataplane/router/router.go`
- [Backend MCP client](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/dataplane/client/client.go): `internal/dataplane/client/client.go`
- [MCP sessions](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/dataplane/session/session.go): `internal/dataplane/session/session.go`
- [Skills validation](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/skills/validate.go): `internal/skills/validate.go`

### LLM proxy

- [LLM request router](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/llmplane/router.go): `internal/llmplane/router.go`
- [Dialect translation](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/llmplane/translate/engine.go): `internal/llmplane/translate/engine.go`
- [LLM providers](https://github.com/tuskira/ai-agent-gateway/tree/main/internal/llmplane): `internal/llmplane`
- [Tool discovery](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/discovery/discovery.go): `internal/discovery/discovery.go`

### Administration

- [Control API](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/api/router.go): `internal/api/router.go`
- [Admin handlers](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/api/handlers/connectors.go): `internal/api/handlers/connectors.go`
- [Admin console](https://github.com/tuskira/ai-agent-gateway/blob/main/web/src/App.tsx): `web/src/App.tsx`

### Persistence and analytics

- [PostgreSQL store](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/store/postgres/store.go): `internal/store/postgres/store.go`
- [Log ingestion](https://github.com/tuskira/ai-agent-gateway/blob/main/internal/api/handlers/ingest.go): `internal/api/handlers/ingest.go`
- [Analytics sink](https://github.com/tuskira/ai-agent-gateway/blob/main/pkg/sink/clickhouse/ingest.go): `pkg/sink/clickhouse/ingest.go`

### Other components

- **Agent client**
- **MCP server**
- **LLM service**

## Connections

- Agent client → API key auth: authenticates (evidence: `README.md`)
- API key auth → MCP orchestrator: authorizes
- API key auth → LLM request router: authorizes
- Agent client → MCP orchestrator: calls MCP (evidence: `README.md`)
- MCP orchestrator → Tool routing: resolves tools (evidence: `internal/dataplane/orchestrator/orchestrator.go`)
- MCP orchestrator → Backend MCP client: dispatches calls (evidence: `internal/dataplane/orchestrator/orchestrator.go`)
- MCP orchestrator → MCP sessions: uses sessions (evidence: `internal/dataplane/orchestrator/orchestrator.go`)
- MCP orchestrator → Skills validation: serves skills (evidence: `README.md`)
- Backend MCP client → MCP server: sends MCP (evidence: `README.md`)
- Agent client → LLM request router: sends LLM calls (evidence: `README.md`)
- LLM request router → Dialect translation: translates dialect (evidence: `internal/llmplane/translate/engine.go`)
- LLM request router → LLM providers: routes requests (evidence: `internal/llmplane/server.go`)
- LLM providers → LLM service: calls upstream (evidence: `README.md`)
- LLM request router → Tool discovery: scans responses (evidence: `internal/llmplane/router.go`)
- Gateway process → Control API: starts plane (evidence: `cmd/gateway/main.go`)
- Gateway process → MCP orchestrator: starts plane (evidence: `cmd/gateway/main.go`)
- Gateway process → LLM request router: starts plane
- Admin console → Control API: uses REST
- Control API → Admin handlers: routes requests (evidence: `internal/api/router.go`)
- Admin handlers → PostgreSQL store: manages records
- Agent client → Log ingestion: submits logs (evidence: `internal/api/handlers/ingest.go`)
- Log ingestion → Analytics sink: writes records
- LLM request router → Analytics sink: captures calls (evidence: `README.md`)
- Control API → PostgreSQL store: requires persistence (evidence: `README.md`)
