# microsoft/mcp-gateway architecture

> Architecture diagram of the GitHub repository microsoft/mcp-gateway, 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/microsoft/mcp-gateway
- Repository: https://github.com/microsoft/mcp-gateway

## Overview

MCP Gateway combines a Kubernetes-backed control plane with a stateless MCP data plane: clients manage adapter/tool resources or send independent MCP requests, which are authorized and routed to running servers. The portal is a management client; optional agent sessions add Foundry-backed runs and SSE events. Edges are limited to relationships shown in excerpts, SOURCE INDEX references, or README claims; several unsampled controller and agent internals are therefore represented at subsystem level.

Main entry points: [`dotnet/Microsoft.McpGateway.Service/src/Program.cs`](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Program.cs) (Gateway host), [`dotnet/Microsoft.McpGateway.Service/src/Controllers/AdapterReverseProxyController.cs`](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Controllers/AdapterReverseProxyController.cs) (Adapter MCP route), [`dotnet/Microsoft.McpGateway.Management/src/Deployment/KubernetesAdapterDeploymentManager.cs`](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Deployment/KubernetesAdapterDeploymentManager.cs) (Kubernetes deployment), [`dotnet/Microsoft.McpGateway.Management/src/Service/AdapterManagementService.cs`](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Service/AdapterManagementService.cs) (Adapter lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Gateway service"]
  node_gateway_service["Gateway host<br/>[Program.cs]"]
  node_adapter_route["Adapter MCP route"]
end

subgraph group_management["Management plane"]
  node_authorization["Access control<br/>[Authorization]"]
  node_adapter_api["Adapter management"]
  node_tool_api["Tool management"]
  node_adapter_service["Adapter lifecycle"]
  node_tool_service["Tool lifecycle"]
  node_deployment["Kubernetes deployment"]
  node_kube["Kubernetes API wrapper<br/>[KubeClient.cs]"]
  node_adapter_store[("Adapter metadata<br/>[Store]")]
  node_tool_store[("Tool metadata<br/>[Store]")]
end

subgraph group_runtime["MCP execution"]
  node_tool_route["Tool MCP router<br/>[Program.cs]"]
  node_tool_definition["Tool definition provider"]
  node_tool_executor["HTTP tool executor"]
end

subgraph group_agents["Agents and sessions"]
  node_agent_api["Agent management"]
  node_session_api["Session endpoints"]
  node_session_service["Session orchestration"]
  node_agent_runner["Agent runner<br/>[AgentRunner.cs]"]
  node_foundry["Foundry chat client"]
end

subgraph group_portal["Management portal"]
  node_portal_ui["Portal screens<br/>[App.tsx]"]
  node_portal_api["Portal API client<br/>[client.ts]"]
end

node_data_client(("MCP client"))
node_admin_client(("Management client"))
node_adapter_servers["Adapter instances"]
node_tool_servers["Tool servers"]

node_data_client -->|"sends MCP"| node_gateway_service
node_admin_client -->|"calls APIs"| node_gateway_service
node_gateway_service -->|"routes adapter"| node_adapter_route
node_gateway_service -->|"maps MCP"| node_tool_route
node_adapter_route -->|"reads metadata"| node_adapter_store
node_adapter_route -->|"checks access"| node_authorization
node_adapter_route -->|"proxies requests"| node_adapter_servers
node_gateway_service -->|"serves management"| node_adapter_api
node_gateway_service -->|"serves management"| node_tool_api
node_adapter_api -.->|"invokes lifecycle"| node_adapter_service
node_tool_api -.->|"invokes lifecycle"| node_tool_service
node_adapter_service -.->|"deploys resources"| node_deployment
node_tool_service -->|"deploys resources"| node_deployment
node_deployment -->|"applies workloads"| node_kube
node_adapter_service -.->|"persists metadata"| node_adapter_store
node_tool_service -->|"persists metadata"| node_tool_store
node_deployment -->|"manages workloads"| node_adapter_servers
node_tool_route -->|"loads definitions"| node_tool_definition
node_tool_definition -->|"reads definitions"| node_tool_store
node_tool_route -->|"dispatches tools"| node_tool_executor
node_tool_executor -->|"executes remotely"| node_tool_servers
node_admin_client -->|"uses portal"| node_portal_ui
node_portal_ui -->|"requests data"| node_portal_api
node_portal_api -->|"calls gateway"| node_gateway_service
node_gateway_service -->|"serves preview APIs"| node_agent_api
node_gateway_service -->|"serves preview APIs"| node_session_api
node_session_api -->|"delegates sessions"| node_session_service
node_session_service -->|"streams agent run"| node_agent_runner
node_agent_runner -.->|"uses chat model"| node_foundry

click node_gateway_service "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Program.cs"
click node_adapter_route "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Controllers/AdapterReverseProxyController.cs"
click node_tool_route "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Tools/src/Program.cs"
click node_authorization "https://github.com/microsoft/mcp-gateway/tree/main/dotnet/Microsoft.McpGateway.Management/src/Authorization"
click node_adapter_api "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Controllers/ManagementController.cs"
click node_tool_api "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Controllers/ToolManagementController.cs"
click node_adapter_service "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Service/AdapterManagementService.cs"
click node_tool_service "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Service/ToolManagementService.cs"
click node_deployment "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Deployment/KubernetesAdapterDeploymentManager.cs"
click node_kube "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Deployment/KubeClient.cs"
click node_adapter_store "https://github.com/microsoft/mcp-gateway/tree/main/dotnet/Microsoft.McpGateway.Management/src/Store"
click node_tool_store "https://github.com/microsoft/mcp-gateway/tree/main/dotnet/Microsoft.McpGateway.Management/src/Store"
click node_tool_definition "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Tools/src/Services/StorageToolDefinitionProvider.cs"
click node_tool_executor "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Tools/src/Services/HttpToolExecutor.cs"
click node_agent_api "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Controllers/AgentManagementController.cs"
click node_session_api "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Controllers/SessionManagementController.cs"
click node_session_service "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Service/SessionManagementService.cs"
click node_agent_runner "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Foundry/AgentRunner.cs"
click node_foundry "https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Foundry/FoundryChatClient.cs"
click node_portal_ui "https://github.com/microsoft/mcp-gateway/blob/main/portal/src/App.tsx"
click node_portal_api "https://github.com/microsoft/mcp-gateway/blob/main/portal/src/api/client.ts"

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_service,node_adapter_route,node_data_client,node_admin_client toneBlue
class node_authorization,node_adapter_api,node_tool_api,node_adapter_service,node_tool_service,node_deployment,node_kube,node_adapter_store,node_tool_store toneAmber
class node_tool_route,node_tool_definition,node_tool_executor,node_tool_servers toneMint
class node_agent_api,node_session_api,node_session_service,node_agent_runner,node_foundry toneRose
class node_portal_ui,node_portal_api,node_adapter_servers toneIndigo
```

## Components

### Gateway service

- [Gateway host](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Program.cs): `dotnet/Microsoft.McpGateway.Service/src/Program.cs`
- [Adapter MCP route](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Controllers/AdapterReverseProxyController.cs): `dotnet/Microsoft.McpGateway.Service/src/Controllers/AdapterReverseProxyController.cs`

### Management plane

- [Access control](https://github.com/microsoft/mcp-gateway/tree/main/dotnet/Microsoft.McpGateway.Management/src/Authorization): `dotnet/Microsoft.McpGateway.Management/src/Authorization`
- [Adapter management](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Controllers/ManagementController.cs): `dotnet/Microsoft.McpGateway.Service/src/Controllers/ManagementController.cs`
- [Tool management](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Controllers/ToolManagementController.cs): `dotnet/Microsoft.McpGateway.Service/src/Controllers/ToolManagementController.cs`
- [Adapter lifecycle](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Service/AdapterManagementService.cs): `dotnet/Microsoft.McpGateway.Management/src/Service/AdapterManagementService.cs`
- [Tool lifecycle](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Service/ToolManagementService.cs): `dotnet/Microsoft.McpGateway.Management/src/Service/ToolManagementService.cs`
- [Kubernetes deployment](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Deployment/KubernetesAdapterDeploymentManager.cs): `dotnet/Microsoft.McpGateway.Management/src/Deployment/KubernetesAdapterDeploymentManager.cs`
- [Kubernetes API wrapper](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Deployment/KubeClient.cs): `dotnet/Microsoft.McpGateway.Management/src/Deployment/KubeClient.cs`
- [Adapter metadata](https://github.com/microsoft/mcp-gateway/tree/main/dotnet/Microsoft.McpGateway.Management/src/Store): `dotnet/Microsoft.McpGateway.Management/src/Store`
- [Tool metadata](https://github.com/microsoft/mcp-gateway/tree/main/dotnet/Microsoft.McpGateway.Management/src/Store): `dotnet/Microsoft.McpGateway.Management/src/Store`

### MCP execution

- [Tool MCP router](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Tools/src/Program.cs): `dotnet/Microsoft.McpGateway.Tools/src/Program.cs`
- [Tool definition provider](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Tools/src/Services/StorageToolDefinitionProvider.cs): `dotnet/Microsoft.McpGateway.Tools/src/Services/StorageToolDefinitionProvider.cs`
- [HTTP tool executor](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Tools/src/Services/HttpToolExecutor.cs): `dotnet/Microsoft.McpGateway.Tools/src/Services/HttpToolExecutor.cs`

### Agents and sessions

- [Agent management](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Controllers/AgentManagementController.cs): `dotnet/Microsoft.McpGateway.Service/src/Controllers/AgentManagementController.cs`
- [Session endpoints](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Service/src/Controllers/SessionManagementController.cs): `dotnet/Microsoft.McpGateway.Service/src/Controllers/SessionManagementController.cs`
- [Session orchestration](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Service/SessionManagementService.cs): `dotnet/Microsoft.McpGateway.Management/src/Service/SessionManagementService.cs`
- [Agent runner](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Foundry/AgentRunner.cs): `dotnet/Microsoft.McpGateway.Management/src/Foundry/AgentRunner.cs`
- [Foundry chat client](https://github.com/microsoft/mcp-gateway/blob/main/dotnet/Microsoft.McpGateway.Management/src/Foundry/FoundryChatClient.cs): `dotnet/Microsoft.McpGateway.Management/src/Foundry/FoundryChatClient.cs`

### Management portal

- [Portal screens](https://github.com/microsoft/mcp-gateway/blob/main/portal/src/App.tsx): `portal/src/App.tsx`
- [Portal API client](https://github.com/microsoft/mcp-gateway/blob/main/portal/src/api/client.ts): `portal/src/api/client.ts`

### Other components

- **MCP client**
- **Management client**
- **Adapter instances**
- **Tool servers**

## Connections

- MCP client → Gateway host: sends MCP (evidence: `README.md`)
- Management client → Gateway host: calls APIs (evidence: `README.md`)
- Gateway host → Adapter MCP route: routes adapter (evidence: `dotnet/Microsoft.McpGateway.Service/src/Program.cs`)
- Gateway host → Tool MCP router: maps MCP (evidence: `dotnet/Microsoft.McpGateway.Tools/src/Program.cs`)
- Adapter MCP route → Adapter metadata: reads metadata (evidence: `dotnet/Microsoft.McpGateway.Service/src/Controllers/AdapterReverseProxyController.cs`)
- Adapter MCP route → Access control: checks access (evidence: `dotnet/Microsoft.McpGateway.Service/src/Controllers/AdapterReverseProxyController.cs`)
- Adapter MCP route → Adapter instances: proxies requests (evidence: `README.md`)
- Gateway host → Adapter management: serves management (evidence: `README.md`)
- Gateway host → Tool management: serves management (evidence: `README.md`)
- Adapter management → Adapter lifecycle: invokes lifecycle
- Tool management → Tool lifecycle: invokes lifecycle
- Adapter lifecycle → Kubernetes deployment: deploys resources
- Tool lifecycle → Kubernetes deployment: deploys resources (evidence: `dotnet/Microsoft.McpGateway.Management/src/Service/ToolManagementService.cs`)
- Kubernetes deployment → Kubernetes API wrapper: applies workloads (evidence: `dotnet/Microsoft.McpGateway.Management/src/Deployment/KubernetesAdapterDeploymentManager.cs`)
- Adapter lifecycle → Adapter metadata: persists metadata
- Tool lifecycle → Tool metadata: persists metadata (evidence: `dotnet/Microsoft.McpGateway.Management/src/Service/ToolManagementService.cs`)
- Kubernetes deployment → Adapter instances: manages workloads (evidence: `README.md`)
- Tool MCP router → Tool definition provider: loads definitions (evidence: `dotnet/Microsoft.McpGateway.Tools/src/Program.cs`)
- Tool definition provider → Tool metadata: reads definitions (evidence: `dotnet/Microsoft.McpGateway.Tools/src/Services/StorageToolDefinitionProvider.cs`)
- Tool MCP router → HTTP tool executor: dispatches tools (evidence: `dotnet/Microsoft.McpGateway.Tools/src/Program.cs`)
- HTTP tool executor → Tool servers: executes remotely (evidence: `README.md`)
- Management client → Portal screens: uses portal (evidence: `README.md`)
- Portal screens → Portal API client: requests data (evidence: `portal/src/App.tsx`)
- Portal API client → Gateway host: calls gateway (evidence: `README.md`)
- Gateway host → Agent management: serves preview APIs (evidence: `README.md`)
- Gateway host → Session endpoints: serves preview APIs (evidence: `README.md`)
- Session endpoints → Session orchestration: delegates sessions (evidence: `dotnet/Microsoft.McpGateway.Service/src/Controllers/SessionManagementController.cs`)
- Session orchestration → Agent runner: streams agent run (evidence: `dotnet/Microsoft.McpGateway.Management/src/Service/SessionManagementService.cs`)
- Agent runner → Foundry chat client: uses chat model
