mcp-gateway

MCP Gateway

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

Table of Contents

Overview

This project provides:

Key Concepts

Architecture

flowchart LR
    subgraph Clients["Clients"]
        DataClient["Agent/MCP Data<br>Client"]
        MgmtClient["Server Management<br>Client"]
    end

    subgraph DataPlane["Data Plane"]
        Routing["Distributed Routing"]
    end

    subgraph ControlPlane["Control Plane"]
        DeploymentManagement["Deployment Management"]
        MetadataManagement["Metadata Management"]
    end

    subgraph Gateway["MCP Gateway"]
        Auth["AuthN - Bearer<br>AuthZ - RBAC/ACL"]
        Auth2["AuthN - Bearer<br>AuthZ - RBAC/ACL"]
        DataPlane
        ControlPlane
    end

    subgraph Cluster["Kubernetes Cluster"]
        PodA["Server Pod<br>mcp-a-0"]
        PodA1["Server Pod<br>mcp-a-1"]
        PodB["Server Pod<br>mcp-b-0"]
    end

    DataClient -- SSE/<br>Streamable HTTP --> Auth
    MgmtClient -- "CRUD /adapters" --> Auth2 --> ControlPlane
    Auth --> Routing
    Routing -- Session Affinity Routing --> PodA
    Routing --> PodA1 & PodB
    MetadataManagement --> Metadata[("Server<br>Metadata")]
    DeploymentManagement -- "Deployment/Status Check"--> Cluster

Features

Control Plane – RESTful APIs for MCP Server Management

Data Plane – Gateway Routing for MCP Servers

Additional Capabilities

Getting Started - Local Deployment

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 mcp-example-server/Dockerfile mcp-example-server -t localhost:5000/mcp-example:1.0.0
docker push localhost:5000/mcp-example:1.0.0

4. Build & Publish MCP Gateway

(Optional) Open dotnet/Microsoft.McpGateway.sln with Visual Studio.

Publish the MCP Gateway image by right-clicking Publish on Microsoft.McpGateway.Service in Visual Studio, or run:

dotnet publish dotnet/Microsoft.McpGateway.Service/src/Microsoft.McpGateway.Service.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. 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

3. Deploy Service Resources

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 resouce 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 mcp-example-server/Dockerfile mcp-example-server -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. Clean the Environment

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

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

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