# Mcp Gateway

> 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.

- **Type:** MCP server
- **Install:** `agentstack add mcp-microsoft-mcp-gateway`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [microsoft](https://agentstack.voostack.com/s/microsoft)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [microsoft](https://github.com/microsoft)
- **Source:** https://github.com/microsoft/mcp-gateway
- **Website:** https://microsoft.github.io/mcp-gateway/

## Install

```sh
agentstack add mcp-microsoft-mcp-gateway
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Gateway

**MCP Gateway** is a reverse proxy and management layer for [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 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

```mermaid
flowchart LR
    subgraph Clients[" "]
        direction TB
        DataClient["🔌 Agent/MCPData Client"]
        MgmtClient["⚙️ ManagementClient"]
    end

    subgraph Gateway["MCP Gateway"]
        direction TB
        
        subgraph Auth1["Authentication & Authorization"]
            Auth["🔐 Data Plane AuthBearer Token / RBAC"]
            Auth2["🔐 Control Plane AuthBearer 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 StoreServer & 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 servers and tools:

- **Read** access is granted to the resource creator, principals assigned the configured `requiredRoles` values (for example `mcp.engineer`), and anyone holding the mandatory administrator role `mcp.admin`. When `requiredRoles` is empty or omitted, only the creator and `mcp.admin` principals can read the resource.
- **Write** access is restricted to the resource creator or principals holding the `mcp.admin` role.

For step-by-step guidance on configuring Azure Entra ID (creating `mcp.admin` and other role values, assigning them to users or service principals, and supplying those values in adapter/tool payloads), see [docs/entra-app-roles.md](docs/entra-app-roles.md).

### Additional Capabilities

- Support for **Proxying Local & Remote MCP Servers**. See [examples and usage](sample-servers/mcp-proxy/README.md).
- Stateless reverse proxy with a distributed session store (production mode).
- Kubernetes-native deployment using StatefulSets and headless services.
- **Management portal** (React SPA) served by the gateway itself at
  [`/portal/`](portal/README.md) — list / create / edit / delete adapters and
  tools, inspect status and pod logs, and exercise each MCP server with an
  in-browser JSON-RPC test console. Authentication mirrors the API: anonymous
  in dev mode (with an optional dev-identity switcher) and MSAL / Entra ID in
  cloud mode, so every list call already filters down to the resources the
  signed-in user is allowed to see.

### Tool Registration and Dynamic Routing

The MCP Gateway now supports **tool registration** with dynamic routing capabilities, enabling a scalable architecture for managing and executing MCP tools.

### How It Works

1. **Tool Registration**: Developers register tools via the `/tools` API endpoint, providing:
   - Container image details (name and version)
   - MCP tool definition (name, description, input schema)
   - Execution endpoint configuration (port and path)
   - Deployment configuration (replicas, environment variables)

2. **Tool Gateway Router**: A specialized MCP server that acts as an intelligent router:
   - Runs as multiple instances behind the gateway for high availability
   - Maintains awareness of all registered tools and their definitions
   - Dynamically routes tool execution requests to the appropriate tool server
   - Accessed via `POST /mcp` endpoint (without adapter name)

3. **Dynamic Routing**: When clients send MCP requests to `/mcp`:
   - The gateway routes requests to available tool gateway router instances with session affinity
   - The router analyzes the tool call in the request
   - Based on the tool definition, it forwards the execution to the correct registered tool server
   - Results are returned through the router back to the client

### Agents and Sessions (Preview)

> **Preview / single-replica.** This subsystem is opt-in and intended for evaluation and single-pod deployments. Built-in tools execute in-process inside the gateway pod, and per-session state (working directory, disk-quota counters) is local to that pod. Do not enable this in a multi-replica or multi-tenant production deployment without adding an out-of-process sandbox and shared session storage.

The gateway can optionally run LLM-driven *agents* that call registered MCP tools and a small set of built-in tools (`builtin:bash`, `builtin:read_file`, `builtin:write_file`). The agent CRUD endpoints (`/agents`, `/sessions` GET/DELETE/LIST) are always available, but **streaming session execution** (`POST /sessions/run`, `POST /sessions/{id}/messages`) is only enabled when `FoundrySettings:Endpoint` is configured. Without it, a streaming request fails fast with an `error` SSE event saying that Foundry must be configured.

#### Enabling

Add a `FoundrySettings` section to `appsettings.json` (or supply via environment variables):

```json
{
  "FoundrySettings": {
    "Endpoint": "https://.cognitiveservices.azure.com/",
    "DeploymentName": "gpt-4o"
  }
}
```

Authentication uses `DefaultAzureCredential`; grant the gateway's identity (managed identity in AKS, or your local user via `az login`) the *Cognitive Services User* role on the target resource. Tool-emitting models are required for any agent with a non-empty `tools` array — `gpt-4o`-class deployments are recommended.

#### Defining an agent

```http
POST /agents
Authorization: Bearer 
Content-Type: application/json
```
```json
{
  "name": "weather-helper",
  "model": "gpt-4o",
  "system": "You answer weather questions concisely.",
  "tools": ["mcp:weather"],
  "description": "Demo agent backed by the weather MCP tool."
}
```

`tools` entries are namespaced by prefix:
- `mcp:` — routes to a tool registered via `/tools`.
- `agent:` — delegates to another agent (subagent / Task pattern).
- `builtin:bash`, `builtin:read_file`, `builtin:write_file` — in-process built-ins (see *Built-in tools and limits* below).

Referenced `mcp:` and `agent:` resources are validated at agent create/update time: the call fails if the resource does not exist or the caller lacks read access, so an agent can never reference tools or peer agents the creator could not invoke directly.

#### Running a session

```http
POST /sessions/run
Authorization: Bearer 
Content-Type: application/json
Accept: text/event-stream
```
```json
{ "agentName": "weather-helper", "input": "What's the weather in Seattle?" }
```

The response is a Server-Sent Events stream; each event is `event: \ndata: \n\n`. Event types include `Started`, `ToolCallStarted`, `ToolCallCompleted`, `TokenDelta`, `Completed`, and `Failed`.

To continue an existing session with a follow-up message:

```http
POST /sessions/{id}/messages
Content-Type: application/json

{ "input": "And in Portland?" }
```

#### Built-in tools and limits

When an agent lists `builtin:bash` / `builtin:read_file` / `builtin:write_file` in its `tools`, those built-ins run **in the gateway pod** under a per-session working directory. They are guarded by:

- A scrubbed, default-deny process environment for `builtin:bash`: the spawned shell receives only a minimal allowlist (`PATH`, locale, `TERM`, `TZ`) with `HOME` / `TMPDIR` / `PWD` pinned to the session directory. The full gateway process environment is not inherited.
- A regex denylist for clearly dangerous shell operations (`sudo`, network egress, mounts, package managers, etc.). This is *defense-in-depth*, not a sandbox.
- 30s default / 120s max bash timeout; 16 KiB output cap per stream; 256 KiB max file size; 4 MiB total writes per session.
- Path resolution rejects absolute paths and `..` traversal.

For multi-tenant or production use, replace these with a real per-session sandbox (e.g. ephemeral pod, gVisor, firejail) — see the inline comments in `BuiltinToolExecutor.cs`.

## Getting Started - Local Deployment

### 1. Prepare Local Development Environment
- [Install .NET 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
- [Install Docker Desktop](https://docs.docker.com/desktop/)
- [Install and turn on Kubernetes](https://docs.docker.com/desktop/features/kubernetes/#install-and-turn-on-kubernetes)

### 2. Run Local Docker Registry
   ```sh
   docker run -d -p 5000:5000 --name registry registry:2.7
   ```

### 3. Build & Publish MCP Server Images
Build and push the MCP server images to your local registry (`localhost:5000`).
```sh
docker build -f sample-servers/mcp-example/Dockerfile sample-servers/mcp-example -t localhost:5000/mcp-example:1.0.0
docker push localhost:5000/mcp-example:1.0.0
```

### 4. Build & Publish MCP Gateway and Tool Gateway Router
(Optional) Open `dotnet/Microsoft.McpGateway.sln` with Visual Studio.

Publish the MCP Gateway image:
```sh
dotnet publish dotnet/Microsoft.McpGateway.Service/src/Microsoft.McpGateway.Service.csproj -c Release /p:PublishProfile=localhost_5000.pubxml
```

Publish the Tool Gateway Router image:
```sh
dotnet publish dotnet/Microsoft.McpGateway.Tools/src/Microsoft.McpGateway.Tools.csproj -c Release /p:PublishProfile=localhost_5000.pubxml
```

### 5. Deploy MCP Gateway to Kubernetes Cluster
Apply the deployment manifests:
```sh
kubectl apply -f deployment/k8s/local-deployment.yml
```

### 6. Enable Port Forwarding
Forward the gateway service port:
```sh
kubectl port-forward -n adapter svc/mcpgateway-service 8000:8000
```

### 7. Test the API - MCP Server Management
- Import the OpenAPI definition from `openapi/mcp-gateway.openapi.json` into tools like [Postman](https://www.postman.com/), [Bruno](https://www.usebruno.com/), or [Swagger Editor](https://editor.swagger.io/).

- Send a request to create a new adapter resource:
  ```http
  POST http://localhost:8000/adapters
  Content-Type: application/json
  ```
   ```json
   {
      "name": "mcp-example",
      "imageName": "mcp-example",
      "imageVersion": "1.0.0",
      "description": "test"
   }
   ```

### 8. Test the API - MCP Server Access 
- After deploying the MCP server, use a client like [VS Code](https://code.visualstudio.com/) to test the connection. Refer to the guide: [Use MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). 
  > **Note:** Ensure VSCode is up to date to access the latest MCP features.

  - To connect to the deployed `mcp-example` server, use:  
     - `http://localhost:8000/adapters/m

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [microsoft](https://github.com/microsoft)
- **Source:** [microsoft/mcp-gateway](https://github.com/microsoft/mcp-gateway)
- **License:** MIT
- **Homepage:** https://microsoft.github.io/mcp-gateway/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-microsoft-mcp-gateway
- Seller: https://agentstack.voostack.com/s/microsoft
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.