microsoft/mcp-gateway

MCP Gateway – What It Is

MCP Gateway is an open‑source reverse‑proxy and management layer built for the Model Context Protocol (MCP). It runs in a Kubernetes cluster and provides two main planes:

• Control plane – a set of REST APIs that let you create, update, list, and delete MCP server instances (called adapters) and tools that expose additional functionality. The control plane also optionally manages agents and sessions (LLM‑driven workflows) when a Azure Cognitive Services endpoint is supplied.
• Data plane – a stateless reverse‑proxy that routes incoming MCP traffic to the appropriate server. It offers session‑aware routing (all requests with the same session_id go to the same pod) and a Tool Gateway Router that dynamically forwards tool calls to the correct tool container.

The gateway is designed for enterprise deployments: it integrates with Azure Entra ID for bearer‑token authentication and role‑based access control, ships a built‑in React management portal, and can be deployed locally with Docker/Kubernetes or with a one‑click Azure template.

---

Core Concepts

Concept	What It Means
MCP Server (Adapter)	A container that implements the Model Context Protocol – essentially a streamable HTTP endpoint that LLMs can talk to.
Tool	A registered service (container) that implements a specific MCP‑tool definition (name, input schema, execution endpoint).
Tool Gateway Router	An MCP server that sits behind the gateway; it inspects incoming MCP requests, looks up the tool definition, and forwards the call to the right tool container.
Session‑aware routing	Guarantees that all calls bearing the same session_id hit the same backend pod, preserving stateful interactions.
Agents & Sessions (preview)	Optional LLM‑driven agents that can call registered tools (and a few built‑in bash/file tools). Sessions stream events via Server‑Sent Events.

---

Key Features

• RESTful control‑plane API for managing adapters, tools, agents, and sessions (CRUD, status, logs).
• Authentication & RBAC using Azure Entra ID (read/write roles mcp.admin, mcp.engineer, etc.).
• Stateless reverse proxy with a distributed session store for production‑grade scaling.
• Dynamic tool routing – register a new tool once and the router automatically directs calls to it.
• Built‑in management portal (/portal/) for visual CRUD, log inspection, and an in‑browser JSON‑RPC test console.
• Kubernetes‑native deployment (StatefulSets, headless services) and a simple local Docker‑K8s deployment path.
• Optional LLM agents that can invoke tools and built‑in bash/file utilities, with sandbox‑style safety limits.
• Support for both local and remote MCP servers – you can proxy existing MCP endpoints.

---

Typical Use Cases

1. Enterprise AI platform – host many MCP‑compatible LLM back‑ends (e.g., Copilot, custom models) behind a single gateway that handles auth, routing, and lifecycle.
2. Tool‑as‑a‑service – register domain‑specific tools (weather, finance, code execution) once and let any MCP client call them without hard‑coding endpoints.
3. Multi‑tenant development sandbox – developers spin up isolated adapters/tools via the API, test them locally, then promote to production.
4. LLM‑driven agents – create agents that orchestrate multiple tools (e.g., retrieve data, run a script, write a file) and expose them through VS Code’s Copilot chat.
5. Observability & governance – centralize logs, telemetry, and role‑based access for all MCP traffic in a regulated environment.

---

Quick‑Start Summary (Local)

1. Prerequisites – install .NET 8 SDK, Docker Desktop with Kubernetes, and a local Docker registry.
2. Build images – compile the sample MCP server and a sample tool, push them to localhost:5000.
3. Publish gateway images – run dotnet publish with the provided publish profile to produce the gateway and tool‑router containers.
4. Deploy – apply deployment/k8s/local-deployment.yml and port‑forward the service (kubectl port-forward … 8000:8000).
5. Create an adapter – POST to /adapters with JSON { "name": "mcp‑example", "imageName": "mcp‑example", "imageVersion": "1.0.0" }.
6. Register a tool – POST to /tools with a tool definition (e.g., a weather tool) and its container image.
7. Connect a client – point VS Code’s MCP config to http://localhost:8000/adapters/<name>/mcp for direct server access or to http://localhost:8000/mcp for tool routing.
8. (Optional) Enable agents – add a FoundrySettings block with an Azure Cognitive Services endpoint and create agents/sessions via the /agents and /sessions APIs.

---

Where to Find More

• OpenAPI spec – openapi/mcp-gateway.openapi.json (importable into Postman, Swagger UI, etc.)
• Management portal source – portal/README.md
• Entra ID role configuration guide – docs/entra-app-roles.md
• Sample server implementations – sample-servers/mcp-example/ and sample-servers/tool-example/
• Azure deployment guide – the “Deploy to Azure” section with a one‑click template and Entra ID setup steps.

---

Bottom line: MCP Gateway gives you a production‑ready, Kubernetes‑native façade for any Model Context Protocol service, handling authentication, session‑affinity, dynamic tool routing, and optional LLM‑agent orchestration—all through a clean REST API and a ready‑made UI.