microsoft/mcp-gateway

microsoft/mcp-gateway

Description: MCP Gateway is a reverse proxy and management layer for MCP servers, enabling scalable, session-aware stateful routing and lifecycle management of MCP servers in Kubernetes environments.

Language: C#

License: MIT

Stars: 699

Forks: 74

Open issues: 11

Created: 2025-05-14T18:16:35Z

Pushed: 2026-06-19T04:02:13Z

Default branch: main

Fork: no

Archived: no

README:

MCP Gateway

MCP Gateway is a reverse proxy and management layer for Model Context Protocol (MCP) servers, enabling scalable, session-aware routing, authorization and lifecycle management of MCP servers in Kubernetes environments.

Table of Contents

• [Overview](#overview)
• [Key Concepts](#key-concepts)
• [Architecture](#architecture)
• [Features](#features)
• [Getting Started – Local Deployment](#getting-started---local-deployment)
• [Getting Started – 1-Click Deploy to Azure](#getting-started---deploy-to-azure)

Overview

This project provides:

• A data gateway for routing traffic to MCP servers with session affinity.
• A control plane for managing the MCP server lifecycle (deploy, update, delete).
• Enterprise-ready integration points including telemetry, access control and observability.

Key Concepts

• MCP Server: A server implementing the Model Context Protocol, which typically a streamable HTTP endpoint.
• Adapters: Logical resources representing MCP servers in the gateway, managed under the /adapters scope. Designed to coexist with other resource types (e.g., /agents) in a unified AI development platform.
• Tools: Registered resources with MCP tool definitions that can be dynamically routed via the tool gateway router. Each tool includes metadata about its execution endpoint and input schema.
• Tool Gateway Router: An MCP server that acts as an intelligent router, directing tool execution requests to the appropriate registered tool servers based on tool definitions. Multiple router instances may run behind the gateway for session affinity.
• Session-Aware Stateful Routing: Ensures that all requests with a given session_id are consistently routed to the same MCP server instance.
• Agents & Sessions (Preview): Optional, opt-in resources for running LLM-driven agents on top of registered MCP tools. *Agents* are metadata (system prompt + model + allowed tool list); *Sessions* are individual runs that stream events over Server-Sent Events. Disabled unless FoundrySettings:Endpoint is configured.

Architecture

flowchart LR
subgraph Clients[" "]
direction TB
DataClient["🔌 Agent/MCP
Data Client"]
MgmtClient["⚙️ Management
Client"]
end

subgraph Gateway["MCP Gateway"]
direction TB

subgraph Auth1["Authentication & Authorization"]
Auth["🔐 Data Plane Auth
Bearer Token / RBAC"]
Auth2["🔐 Control Plane Auth
Bearer Token / RBAC"]
end

subgraph DataPlane["Data Plane"]
Routing["🔀 Adapter Routing
/adapters/{name}/mcp"]
ToolRouting["🔀 Tool Router Gateway
/mcp"]
end

subgraph ControlPlane["Control Plane"]
direction LR
AdapterMgmt["📦 Adapter Management
/adapters CRUD"]
ToolMgmt["🔧 Tool Management
/tools CRUD"]
end

subgraph Management["Backend Services"]
DeploymentMgmt["☸️ Deployment Manager"]
MetadataMgmt["📋 Metadata Manager"]
end
end

subgraph Cluster["Kubernetes Cluster"]
direction TB

subgraph ServerRow[" "]
direction LR

subgraph MCPServers["MCP Servers"]
direction TB
PodA["mcp-a-0"]
PodA1["mcp-a-1"]
PodB["mcp-b-0"]
end

subgraph ToolRouters["Tool Gateway Routers"]
direction TB
Router1["toolgateway-0"]
Router2["toolgateway-1"]
end
end

subgraph ToolServers["Registered Tool Servers"]
direction LR
Tool1["tool-1-0"]
Tool2["tool-2-0"]
end
end

Metadata[("💾 Metadata Store
Server & Tool Info")]

DataClient -->|"MCP Requests"| Auth
MgmtClient -->|"API Calls"| Auth2

Auth --> Routing
Auth --> ToolRouting
Auth2 --> AdapterMgmt
Auth2 --> ToolMgmt

AdapterMgmt & ToolMgmt --> DeploymentMgmt
AdapterMgmt & ToolMgmt --> MetadataMgmt

Routing -.->|"Session Affinity"| MCPServers
ToolRouting -.->|"Session Affinity"| ToolRouters
ToolRouters ==>|"Dynamic Routing"| ToolServers

DeploymentMgmt -->|"Deploy & Monitor"| Cluster
MetadataMgmt |"Read/Write"| Metadata

style Gateway fill:#e1f5ff
style Cluster fill:#fff4e1
style Metadata fill:#f0f0f0

Features

Control Plane – RESTful APIs for MCP Server Management

MCP Server Management (Adapters)

• POST /adapters — Deploy and register a new MCP server.
• GET /adapters — List all MCP servers the user can access.
• GET /adapters/{name} — Retrieve metadata for a specific adapter.
• GET /adapters/{name}/status — Check the deployment status.
• GET /adapters/{name}/logs — Access the server's running logs.
• PUT /adapters/{name} — Update the deployment.
• DELETE /adapters/{name} — Remove the server.

Tool Registration and Management

• POST /tools — Register and deploy a tool with MCP tool definition metadata.
• GET /tools — List all registered tools the user can access.
• GET /tools/{name} — Retrieve metadata and tool definition for a specific tool.
• GET /tools/{name}/status — Check the tool deployment status.
• GET /tools/{name}/logs — Access the tool server's running logs.
• PUT /tools/{name} — Update a tool deployment and definition.
• DELETE /tools/{name} — Remove a registered tool.

Agent and Session Management (Preview, opt-in)

Available only when FoundrySettings:Endpoint is configured. See [Agents and Sessions](#agents-and-sessions-preview) below for details.

• POST /agents, GET /agents, GET|PUT|DELETE /agents/{name} — CRUD for agent definitions.
• POST /sessions, GET /sessions, GET|DELETE /sessions/{id} — CRUD for sessions.
• POST /sessions/run — Start a session and stream events (SSE).
• POST /sessions/{id}/messages — Continue an existing session with a new user message; streams events (SSE).

Data Plane – Gateway Routing for MCP Servers

Direct MCP Server Access

• POST /adapters/{name}/mcp — Establish a streamable HTTP connection.

Dynamic Tool Routing via Tool Gateway Router

• POST /mcp — Route requests to the tool gateway router, which dynamically routes to registered tools based on tool definitions. The router itself is an MCP server with multiple instances hosted behind the gateway for scalability.

Authentication & Authorization Support

The gateway provides entra id authentication and basic application role authorization for mcp...