mcp-gateway

MCP Gateway

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

Breaking change: this version requires MCP 2026-07-28 clients and adapters. It does not provide legacy initialization, transport sessions, or protocol downgrade. See the migration guide for client requirements, request examples, deployment settings, and rollback considerations.

Table of Contents

Overview

This project provides:

Key Concepts

Architecture

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

    subgraph Gateway["MCP Gateway"]
        direction TB
        
        subgraph Auth1["Authentication & Authorization"]
            Auth["🔐 Data Plane Auth<br>Bearer Token / RBAC"]
            Auth2["🔐 Control Plane Auth<br>Bearer Token / RBAC"]
        end
        
        subgraph DataPlane["Data Plane"]
            Routing["🔀 Adapter Routing<br>/adapters/{name}/mcp"]
            ToolRouting["🔀 Tool Router Gateway<br>/mcp"]
        end

        subgraph ControlPlane["Control Plane"]
            direction LR
            AdapterMgmt["📦 Adapter Management<br>/adapters CRUD"]
            ToolMgmt["🔧 Tool Management<br>/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<br>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 -.->|"Per-Request Routing"| MCPServers
    ToolRouting -.->|"Per-Request Routing"| 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)

Tool Registration and Management

Agent and Session Management (Preview, opt-in)

Available only when FoundrySettings:Endpoint is configured. See Agents and Sessions below for details.

Data Plane – Gateway Routing for MCP Servers

Direct MCP Server Access

Dynamic Tool Routing via Tool Gateway Router

Authentication & Authorization Support

The gateway provides entra id authentication and basic application role authorization for mcp servers and tools:

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.

Additional Capabilities

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 each request to an available tool gateway router instance
    • 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. Session working directories are local to that pod. Built-in tool execution is disabled; registered MCP tools and subagents remain available. Do not enable this in a multi-replica or multi-tenant production deployment without addressing session storage and workload isolation.

The gateway can optionally run LLM-driven agents that call registered MCP tools and other agents. 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):

{
  "FoundrySettings": {
    "Endpoint": "https://<your-resource>.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

POST /agents
Authorization: Bearer <token>
Content-Type: application/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:

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

POST /sessions/run
Authorization: Bearer <token>
Content-Type: application/json
Accept: text/event-stream

{ "agentName": "weather-helper", "input": "What's the weather in Seattle?" }

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

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

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

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

Built-in tools and limits

builtin:bash, builtin:read_file, and builtin:write_file are disabled for all callers, including mcp.admin. BuiltinToolSettings:RequiredRoles and role assignments cannot re-enable them. Shell and file execution have been removed from the built-in executor.

Use separately hosted MCP tools with appropriate workload isolation for operations that require shell or file access.

Getting Started - Local Deployment

The numbered steps below use the default adapter namespace. To test changes without replacing an existing deployment, follow the isolated local E2E steps. Kubernetes__Namespace configures resource deployment and backend DNS; its default remains adapter.

1. Prepare Local Development Environment

2. Run Local Docker Registry

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

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:

dotnet publish dotnet/Microsoft.McpGateway.Service/src/Microsoft.McpGateway.Service.csproj -c Release /p:PublishProfile=localhost_5000.pubxml

Publish the Tool Gateway Router image:

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:

kubectl apply -f deployment/k8s/local-deployment.yml

6. Enable Port Forwarding

Forward the gateway service port:

kubectl port-forward -n adapter svc/mcpgateway-service 8000:8000

7. Test the API - MCP Server Management

8. Test the API - MCP Server Access

9. Test Tool Registration and Dynamic Routing

Build & Publish a Tool Server Image

First, build and push a tool server image to your local registry:

docker build -f sample-servers/tool-example/Dockerfile sample-servers/tool-example -t localhost:5000/weather-tool:1.0.0
docker push localhost:5000/weather-tool:1.0.0

Register a Tool

Send a request to register a tool with its definition:

POST http://localhost:8000/tools
Content-Type: application/json

{
  "name": "weather",
  "imageName": "weather-tool",
  "imageVersion": "1.0.0",
  "description": "Weather tool for getting current weather information",
  "toolDefinition": {
    "tool": {
      "name": "weather",
      "title": "Weather Information",
      "description": "Gets the current weather for a specified location.",
      "type": "http",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          }
        },
        "required": ["location"]
      }
    },
    "port": 8000
  }
}

Verify Tool Deployment

Check the tool deployment status:

GET http://localhost:8000/tools/weather/status

Test Tool Routing via Tool Gateway Router

Use an MCP client (like VS Code) to connect to the tool gateway router:

Sample .vscode/mcp.json that connects to the tool gateway router:

{
  "servers": {
    "tool-gateway": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

The router will automatically route tool calls to the appropriate registered tool servers based on the tool name in the MCP request.

10. Clean the Environment

To remove all deployed resources, delete the Kubernetes namespace:

   kubectl delete namespace adapter

Getting Started - Deploy to Azure

Cloud Infrastructure

Architecture Diagram

1. Prepare Cloud Development Environment

2. Setup Entra ID (Azure Active Directory)

The cloud-deployed service requires bearer token authentication using Azure Entra ID. Follow these steps to configure an app registration.

Create and Configure the App Registration

  1. Go to App Registrations
  2. Click + New registration
    • Name: Choose a meaningful name, e.g., mcp-gateway
    • Supported account types: Select Single tenant
    • Click Register
  3. Go to the app registration Overview and copy:
    • Application (client) ID — this is your API Client ID for deployment

Expose an API (Define a Scope)

  1. In the left menu, go to Expose an API
  2. Click Add next to Application ID URI, and leave it as the default value: 
    api://<your-client-id>
  3. Click + Add a scope
    • Scope name: access
    • Admin consent display name: Access MCP Gateway
    • Admin consent Description: Any brief description
    • Click Add scope

Authorize Azure CLI & VS Code as a Client Application

To allow Azure CLI & VS Code to work as the client for token acquisition.

  1. Still in Expose an API, scroll down to Authorized client applications
  2. Click + Add a client application
    • Client ID: 04b07795-8ddb-461a-bbee-02f9e1bf7b46 (Azure CLI)
    • Client ID: aebc6443-996d-45c2-90f0-388ff96faa56 (VS Code)
    • In Authorized scopes, select the scope access
    • Click Add

Configure Application Role for Authorization

docs/entra-app-roles.md

3. Deploy Service Resources

For source-change validation, use the checked-out deployment script, not the portal button or published latest images. It supports -SubscriptionId, -TenantId, -Stage Infrastructure|Kubernetes|All, -GatewayImage, and -ToolGatewayImage. Build and push both changed first-party images to ACR between the Infrastructure and Kubernetes stages.

Use -NodeCount 1 -NodeVmSize Standard_D4as_v5 -AcrSku Basic -CosmosServerless only for a new, isolated short-lived test account/cluster after regional capacity validation. Production defaults remain two Standard_D4ds_v5 nodes. Cosmos serverless is not an in-place conversion of an existing account.

Before sending bearer tokens, configure an HTTPS listener by supplying a secure ARM parameter file with tlsCertificateData (base64 PFX) and tlsCertificatePassword through -SecureParametersFile. Keep the file outside source control. The script uses the local Kubernetes manifest, exact image inputs, and a generated or existing gateway secret; it does not download a manifest from main. See cloud E2E steps for a complete validation sequence.

Deploy to Azure

Parameters | Name | Description | |——————-|——————————————————————————————————————| | resourceGroup | The name of the resource group. Must contain only lowercase letters and numbers (alphanumeric). | | clientId | The Entra ID (Azure AD) client ID from your app registration. | | location | (Optional) The Azure region where resources will be deployed.
Defaults to the resource group’s location. | | resourceLabel | (Optional) A lowercase alphanumeric string used as a suffix for naming resources and as the DNS label.
If not provided, it will be the resourceGroup name.
Recommendation: Set this value as the default the same with resource group name and make sure resource group name contains only lower alphanumeric. |

The deployment will:

Note: It’s recommended to use Managed Identity for credential-less authentication. This deployment follows that design.

4. Build & Publish MCP Server Images

The gateway service pulls the MCP server image from the newly provisioned Azure Container Registry (ACR) during deployment.

Build the MCP server image in ACR:

az acr build -r "mgreg$resourceLabel" -f sample-servers/mcp-example/Dockerfile sample-servers/mcp-example -t "mgreg$resourceLabel.azurecr.io/mcp-example:1.0.0"

5. Test the API - MCP Server Management

6. Test the API - MCP Server Access

7. Test Tool Registration and Dynamic Routing

Build & Publish a Tool Server Image

Build and push a tool server image to ACR:

az acr build -r "mgreg$resourceLabel" -f sample-servers/tool-example/Dockerfile sample-servers/tool-example -t "mgreg$resourceLabel.azurecr.io/weather-tool:1.0.0"

Register a Tool

Acquire a bearer token:

az account get-access-token --resource $clientId

Send a request to register a tool with its definition:

POST https://<resourceLabel>.<location>.cloudapp.azure.com/tools
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "weather",
  "imageName": "weather-tool",
  "imageVersion": "1.0.0",
  "useWorkloadIdentity": true,
  "description": "Weather tool for getting current weather information",
  "requiredRoles": [], // Only creator and mcp.admin can access. Add roles (e.g. ["mcp.engineer"]) to grant read access to other principals.
  "toolDefinition": {
    "tool": {
      "name": "weather",
      "title": "Weather Information",
      "description": "Gets the current weather for a specified location.",
      "type": "http",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          }
        },
        "required": ["location"]
      },
      "annotations": {
        "readOnly": true
      }
    },
    "port": 8000
  }
}

Verify Tool Deployment

Check the tool deployment status:

GET https://<resourceLabel>.<location>.cloudapp.azure.com/tools/weather/status
Authorization: Bearer <token>

Test Tool Routing via Tool Gateway Router

Use an MCP client (like VS Code) to connect to the tool gateway router:

Sample .vscode/mcp.json that connects to the tool gateway router:

{
  "servers": {
    "tool-gateway": {
      "url": "https://<resourceLabel>.<location>.cloudapp.azure.com/mcp"
    }
  }
}

Note: Authentication is required. VS Code will handle the authentication process.

The router will automatically route tool calls to the appropriate registered tool servers based on the tool name in the MCP request.

8. Clean the Environment

To remove all deployed resources, delete the resource group from Azure portal or run:

az group delete --name <resourceGroupName> --yes

9. Production Onboarding

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.

Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

This site is open source. Improve this page.