Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/microsoft/mcp-gateway with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/microsoft/mcp-gateway'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/microsoft--mcp-gateway/badge.svg)](/listings/microsoft--mcp-gateway)

HTML

<a href="/listings/microsoft--mcp-gateway"><img src="/api/listings/microsoft--mcp-gateway/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

The numbered steps below use the default `adapter` namespace. To test changes without replacing an existing deployment, follow [the isolated local E2E steps](deployment/e2e/README.md#local-e2e). `Kubernetes__Namespace` configures resource deployment and backend DNS; its default remains `adapter`.

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

   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

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

  POST http://localhost:8000/adapters
  Content-Type: application/json
   {
      "name": "mcp-example",
      "imageName": "mcp-example",
      "imageVersion": "1.0.0",
      "description": "test"
   }

8. Test the API - MCP Server Access

- Use a client that supports MCP `2026-07-28`. `server/discover` is optional; direct `tools/list` and `tools/call` do not require a handshake. Every request must include the protocol version and client capabilities in `params._meta`, plus `MCP-Protocol-Version` and `Mcp-Method` headers. `tools/call` also requires `Mcp-Name` and any schema-annotated `Mcp-Param-*` headers. - GET/DELETE on MCP endpoints return `405`; legacy initialization is rejected. Long-lived notification streams use `POST subscriptions/listen` with a `params.notifications` filter, when supported by the adapter. - 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/mcp-example/mcp` (Streamable HTTP)

Sample `.vscode/mcp.json` that connects to the `mcp-example` server

  {
    "servers": {
      "mcp-example": {
        "url": "http://localhost:8000/adapters/mcp-example/mcp",
      }
    }
  }

- For other servers: - `http://localhost:8000/adapters/{name}/mcp` (Streamable HTTP)

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:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 726 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Gateway
  2. **MCP Gateway** is a reverse proxy and management layer for [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) servers, enabling scalable, stateless request routing, authorization and lifecycle management of MCP servers in Kubernetes environments.
  3. > **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](docs/mcp-2026-07-28.md) for client requirements, request examples, deployment settings, and rollback considerations.
  4. ## Table of Contents
  5. - [Overview](#overview)
  6. - [Key Concepts](#key-concepts)
  7. - [Architecture](#architecture)
  8. - [Features](#features)
  9. - [Getting Started – Local Deployment](#getting-started---local-deployment)
  10. - [Getting Started – 1-Click Deploy to Azure](#getting-started---deploy-to-azure)
  11. ## Overview
  12. This project provides:
  13. - A data gateway for independently routing each MCP request to a ready server instance.
  14. - A control plane for managing the MCP server lifecycle (deploy, update, delete).
  15. - Enterprise-ready integration points including telemetry, access control and observability.
  16. ## Key Concepts
  17. - **MCP Server**: A server implementing the Model Context Protocol, which typically a streamable HTTP endpoint.
  18. - **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.
  19. - **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.
  20. - **Tool Gateway Router**: An MCP server that directs tool execution requests to registered tool servers based on tool definitions. Multiple router instances can handle requests without transport-session affinity.
  21. - **Stateless MCP Routing**: Each request carries its protocol metadata and is independently authorized. Legacy session headers and the gateway's `session_id` query alias do not determine routing.
  22. - **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.
  23. ## Architecture
  24. ```mermaid
  25. flowchart LR
  26. subgraph Clients[" "]
  27. direction TB
  28. DataClient["🔌 Agent/MCP<br>Data Client"]
  29. MgmtClient["⚙️ Management<br>Client"]
  30. end
  31. subgraph Gateway["MCP Gateway"]
  32. direction TB
  33. subgraph Auth1["Authentication & Authorization"]
  34. Auth["🔐 Data Plane Auth<br>Bearer Token / RBAC"]
  35. Auth2["🔐 Control Plane Auth<br>Bearer Token / RBAC"]
  36. end
  37. subgraph DataPlane["Data Plane"]
  38. Routing["🔀 Adapter Routing<br>/adapters/{name}/mcp"]
  39. ToolRouting["🔀 Tool Router Gateway<br>/mcp"]
  40. end
  41. subgraph ControlPlane["Control Plane"]
  42. direction LR
  43. AdapterMgmt["📦 Adapter Management<br>/adapters CRUD"]
  44. ToolMgmt["🔧 Tool Management<br>/tools CRUD"]
  45. end
  46. subgraph Management["Backend Services"]
  47. DeploymentMgmt["☸️ Deployment Manager"]
  48. MetadataMgmt["📋 Metadata Manager"]
  49. end
  50. end
  51. subgraph Cluster["Kubernetes Cluster"]
  52. direction TB
  53. subgraph ServerRow[" "]
  54. direction LR
  55. subgraph MCPServers["MCP Servers"]
  56. direction TB
  57. PodA["mcp-a-0"]
  58. PodA1["mcp-a-1"]
  59. PodB["mcp-b-0"]
  60. end
  61. subgraph ToolRouters["Tool Gateway Routers"]
  62. direction TB
  63. Router1["toolgateway-0"]
  64. Router2["toolgateway-1"]
  65. end
  66. end
  67. subgraph ToolServers["Registered Tool Servers"]
  68. direction LR
  69. Tool1["tool-1-0"]
  70. Tool2["tool-2-0"]
  71. end
  72. end
  73. Metadata[("💾 Metadata Store<br>Server & Tool Info")]
  74. DataClient -->|"MCP Requests"| Auth
  75. MgmtClient -->|"API Calls"| Auth2
  76. Auth --> Routing
  77. Auth --> ToolRouting
  78. Auth2 --> AdapterMgmt
  79. Auth2 --> ToolMgmt
  80. AdapterMgmt & ToolMgmt --> DeploymentMgmt
  81. AdapterMgmt & ToolMgmt --> MetadataMgmt
  82. Routing -.->|"Per-Request Routing"| MCPServers
  83. ToolRouting -.->|"Per-Request Routing"| ToolRouters
  84. ToolRouters ==>|"Dynamic Routing"| ToolServers
  85. DeploymentMgmt -->|"Deploy & Monitor"| Cluster
  86. MetadataMgmt <-->|"Read/Write"| Metadata
  87. style Gateway fill:#e1f5ff
  88. style Cluster fill:#fff4e1
  89. style Metadata fill:#f0f0f0
  90. ```
  91. ## Features
  92. ### Control Plane – RESTful APIs for MCP Server Management
  93. #### MCP Server Management (Adapters)
  94. - `POST /adapters` — Deploy and register a new MCP server.
  95. - `GET /adapters` — List all MCP servers the user can access.
  96. - `GET /adapters/{name}` — Retrieve metadata for a specific adapter.
  97. - `GET /adapters/{name}/status` — Check the deployment status.
  98. - `GET /adapters/{name}/logs` — Access the server's running logs.
  99. - `PUT /adapters/{name}` — Update the deployment.
  100. - `DELETE /adapters/{name}` — Remove the server.
  101. #### Tool Registration and Management
  102. - `POST /tools` — Register and deploy a tool with MCP tool definition metadata.
  103. - `GET /tools` — List all registered tools the user can access.
  104. - `GET /tools/{name}` — Retrieve metadata and tool definition for a specific tool.
  105. - `GET /tools/{name}/status` — Check the tool deployment status.
  106. - `GET /tools/{name}/logs` — Access the tool server's running logs.
  107. - `PUT /tools/{name}` — Update a tool deployment and definition.
  108. - `DELETE /tools/{name}` — Remove a registered tool.
  109. #### Agent and Session Management (Preview, opt-in)
  110. Available only when `FoundrySettings:Endpoint` is configured. See [Agents and Sessions](#agents-and-sessions-preview) below for details.
  111. - `POST /agents`, `GET /agents`, `GET|PUT|DELETE /agents/{name}` — CRUD for agent definitions.
  112. - `POST /sessions`, `GET /sessions`, `GET|DELETE /sessions/{id}` — CRUD for sessions.
  113. - `POST /sessions/run` — Start a session and stream events (SSE).
  114. - `POST /sessions/{id}/messages` — Continue an existing session with a new user message; streams events (SSE).
  115. ### Data Plane – Gateway Routing for MCP Servers
  116. #### Direct MCP Server Access
  117. - `POST /adapters/{name}/mcp` — Send an independent MCP request; receive JSON or request-scoped SSE.
  118. #### Dynamic Tool Routing via Tool Gateway Router
  119. - `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.
  120. ### Authentication & Authorization Support
  121. The gateway provides entra id authentication and basic application role authorization for mcp servers and tools:
  122. - **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.
  123. - **Write** access is restricted to the resource creator or principals holding the `mcp.admin` role.
  124. 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).
  125. ### Additional Capabilities
  126. - Support for **Proxying Local & Remote MCP Servers**. See [examples and usage](sample-servers/mcp-proxy/README.md).
  127. - Stateless reverse proxy without MCP transport-session storage. Resource metadata remains in Redis (local Kubernetes) or Cosmos DB (cloud).
  128. - Kubernetes-native deployment using StatefulSets and headless services.
  129. - **Management portal** (React SPA) served by the gateway itself at
  130. [`/portal/`](portal/README.md) — list / create / edit / delete adapters and
  131. tools, inspect status and pod logs, and exercise each MCP server with an
  132. in-browser JSON-RPC test console. Authentication mirrors the API: anonymous
  133. in dev mode (with an optional dev-identity switcher) and MSAL / Entra ID in
  134. cloud mode, so every list call already filters down to the resources the
  135. signed-in user is allowed to see.
  136. ### Tool Registration and Dynamic Routing
  137. The MCP Gateway now supports **tool registration** with dynamic routing capabilities, enabling a scalable architecture for managing and executing MCP tools.
  138. ### How It Works
  139. 1. **Tool Registration**: Developers register tools via the `/tools` API endpoint, providing:
  140. - Container image details (name and version)
  141. - MCP tool definition (name, description, input schema)
  142. - Execution endpoint configuration (port and path)
  143. - Deployment configuration (replicas, environment variables)
  144. 2. **Tool Gateway Router**: A specialized MCP server that acts as an intelligent router:
  145. - Runs as multiple instances behind the gateway for high availability
  146. - Maintains awareness of all registered tools and their definitions
  147. - Dynamically routes tool execution requests to the appropriate tool server
  148. - Accessed via `POST /mcp` endpoint (without adapter name)
  149. 3. **Dynamic Routing**: When clients send MCP requests to `/mcp`:
  150. - The gateway routes each request to an available tool gateway router instance
  151. - The router analyzes the tool call in the request
  152. - Based on the tool definition, it forwards the execution to the correct registered tool server
  153. - Results are returned through the router back to the client
  154. ### Agents and Sessions (Preview)
  155. > **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.
  156. 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.
  157. #### Enabling
  158. Add a `FoundrySettings` section to `appsettings.json` (or supply via environment variables):
  159. ```json
  160. {
  161. "FoundrySettings": {
  162. "Endpoint": "https://<your-resource>.cognitiveservices.azure.com/",
  163. "DeploymentName": "gpt-4o"
  164. }
  165. }
  166. ```
  167. 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.
  168. #### Defining an agent
  169. ```http
  170. POST /agents
  171. Authorization: Bearer <token>
  172. Content-Type: application/json
  173. ```
  174. ```json
  175. {
  176. "name": "weather-helper",
  177. "model": "gpt-4o",
  178. "system": "You answer weather questions concisely.",
  179. "tools": ["mcp:weather"],
  180. "description": "Demo agent backed by the weather MCP tool."
  181. }
  182. ```
  183. `tools` entries are namespaced by prefix:
  184. - `mcp:<tool-name>` — routes to a tool registered via `/tools`.
  185. - `agent:<agent-name>` — delegates to another agent (subagent / Task pattern).
  186. - `builtin:bash`, `builtin:read_file`, `builtin:write_file` - disabled and rejected (see *Built-in tools and limits* below).
  187. 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.
  188. #### Running a session
  189. ```http
  190. POST /sessions/run
  191. Authorization: Bearer <token>
  192. Content-Type: application/json
  193. Accept: text/event-stream
  194. ```
  195. ```json
  196. { "agentName": "weather-helper", "input": "What's the weather in Seattle?" }
  197. ```
  198. 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`.
  199. To continue an existing session with a follow-up message:
  200. ```http
  201. POST /sessions/{id}/messages
  202. Content-Type: application/json
  203. { "input": "And in Portland?" }
  204. ```
  205. #### Built-in tools and limits
  206. `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.
  207. - Creating or updating an agent with a `builtin:` reference returns `400 Bad Request`.
  208. - Existing definitions remain readable and deletable, but their built-in tools are not advertised to the model. Previously resolved built-in calls return a disabled-tool error without executing.
  209. - Remove `builtin:` entries when updating existing agents. Registered `mcp:` tools and `agent:` references are unaffected.
  210. Use separately hosted MCP tools with appropriate workload isolation for operations that require shell or file access.
  211. ## Getting Started - Local Deployment
  212. The numbered steps below use the default `adapter` namespace. To test changes without replacing an existing deployment, follow [the isolated local E2E steps](deployment/e2e/README.md#local-e2e). `Kubernetes__Namespace` configures resource deployment and backend DNS; its default remains `adapter`.
  213. ### 1. Prepare Local Development Environment
  214. - [Install .NET 8 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/8.0)
  215. - [Install Docker Desktop](https://docs.docker.com/desktop/)
  216. - [Install and turn on Kubernetes](https://docs.docker.com/desktop/features/kubernetes/#install-and-turn-on-kubernetes)
  217. ### 2. Run Local Docker Registry
  218. ```sh
  219. docker run -d -p 5000:5000 --name registry registry:2.7
  220. ```
  221. ### 3. Build & Publish MCP Server Images
  222. Build and push the MCP server images to your local registry (`localhost:5000`).
  223. ```sh
  224. docker build -f sample-servers/mcp-example/Dockerfile sample-servers/mcp-example -t localhost:5000/mcp-example:1.0.0
  225. docker push localhost:5000/mcp-example:1.0.0
  226. ```
  227. ### 4. Build & Publish MCP Gateway and Tool Gateway Router
  228. (Optional) Open `dotnet/Microsoft.McpGateway.sln` with Visual Studio.
  229. Publish the MCP Gateway image:
  230. ```sh
  231. dotnet publish dotnet/Microsoft.McpGateway.Service/src/Microsoft.McpGateway.Service.csproj -c Release /p:PublishProfile=localhost_5000.pubxml
  232. ```
  233. Publish the Tool Gateway Router image:
  234. ```sh
  235. dotnet publish dotnet/Microsoft.McpGateway.Tools/src/Microsoft.McpGateway.Tools.csproj -c Release /p:PublishProfile=localhost_5000.pubxml
  236. ```
  237. ### 5. Deploy MCP Gateway to Kubernetes Cluster
  238. Apply the deployment manifests:
  239. ```sh
  240. kubectl apply -f deployment/k8s/local-deployment.yml
  241. ```
  242. ### 6. Enable Port Forwarding
  243. Forward the gateway service port:
  244. ```sh
  245. kubectl port-forward -n adapter svc/mcpgateway-service 8000:8000
  246. ```
  247. ### 7. Test the API - MCP Server Management
  248. - 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/).
  249. - Send a request to create a new adapter resource:
  250. ```http
  251. POST http://localhost:8000/adapters
  252. Content-Type: application/json
  253. ```
  254. ```json
  255. {
  256. "name": "mcp-example",
  257. "imageName": "mcp-example",
  258. "imageVersion": "1.0.0",
  259. "description": "test"
  260. }
  261. ```
  262. ### 8. Test the API - MCP Server Access
  263. - Use a client that supports MCP `2026-07-28`. `server/discover` is optional; direct `tools/list` and `tools/call` do not require a handshake. Every request must include the protocol version and client capabilities in `params._meta`, plus `MCP-Protocol-Version` and `Mcp-Method` headers. `tools/call` also requires `Mcp-Name` and any schema-annotated `Mcp-Param-*` headers.
  264. - GET/DELETE on MCP endpoints return `405`; legacy initialization is rejected. Long-lived notification streams use `POST subscriptions/listen` with a `params.notifications` filter, when supported by the adapter.
  265. - 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).
  266. > **Note:** Ensure VSCode is up to date to access the latest MCP features.
  267. - To connect to the deployed `mcp-example` server, use:
  268. - `http://localhost:8000/adapters/mcp-example/mcp` (Streamable HTTP)
  269. Sample `.vscode/mcp.json` that connects to the `mcp-example` server
  270. ```json
  271. {
  272. "servers": {
  273. "mcp-example": {
  274. "url": "http://localhost:8000/adapters/mcp-example/mcp",
  275. }
  276. }
  277. }
  278. ```
  279. - For other servers:
  280. - `http://localhost:8000/adapters/{name}/mcp` (Streamable HTTP)
  281. ### 9. Test Tool Registration and Dynamic Routing
  282. #### Build & Publish a Tool Server Image
  283. First, build and push a tool server image to your local registry:
  284. ```sh
  285. docker build -f sample-servers/tool-example/Dockerfile sample-servers/tool-example -t localhost:5000/weather-tool:1.0.0
  286. docker push localhost:5000/weather-tool:1.0.0
  287. ```
  288. #### Register a Tool
  289. Send a request to register a tool with its definition:
  290. ```http
  291. POST http://localhost:8000/tools
  292. Content-Type: application/json
  293. ```
  294. ```json
  295. {
  296. "name": "weather",
  297. "imageName": "weather-tool",
  298. "imageVersion": "1.0.0",
  299. "description": "Weather tool for getting current weather information",
  300. "toolDefinition": {
  301. "tool": {
  302. "name": "weather",
  303. "title": "Weather Information",
  304. "description": "Gets the current weather for a specified location.",
  305. "type": "http",
  306. "inputSchema": {
  307. "type": "object",
  308. "properties": {
  309. "location": {
  310. "type": "string",
  311. "description": "The city and state, e.g. San Francisco, CA"
  312. }
  313. },
  314. "required": ["location"]
  315. }
  316. },
  317. "port": 8000
  318. }
  319. }
  320. ```
  321. #### Verify Tool Deployment
  322. Check the tool deployment status:
  323. ```http
  324. GET http://localhost:8000/tools/weather/status
  325. ```
  326. #### Test Tool Routing via Tool Gateway Router
  327. Use an MCP client (like VS Code) to connect to the tool gateway router:
  328. Sample `.vscode/mcp.json` that connects to the tool gateway router:
  329. ```json
  330. {
  331. "servers": {
  332. "tool-gateway": {
  333. "url": "http://localhost:8000/mcp"
  334. }
  335. }
  336. }
  337. ```
  338. The router will automatically route tool calls to the appropriate registered tool servers based on the tool name in the MCP request.
  339. ### 10. Clean the Environment
  340. To remove all deployed resources, delete the Kubernetes namespace:
  341. ```sh
  342. kubectl delete namespace adapter
  343. ```
  344. ## Getting Started - Deploy to Azure
  345. ### Cloud Infrastructure
  346. ![Architecture Diagram](infra-diagram.png)
  347. ### 1. Prepare Cloud Development Environment
  348. - An active [Azure subscription](https://azure.microsoft.com) with **Owner** access
  349. - [Install Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
  350. ### 2. Setup Entra ID (Azure Active Directory)
  351. The cloud-deployed service requires bearer token authentication using Azure Entra ID. Follow these steps to configure an app registration.
  352. #### Create and Configure the App Registration
  353. 1. Go to [App Registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
  354. 2. Click **+ New registration**
  355. - **Name**: Choose a meaningful name, e.g., `mcp-gateway`
  356. - **Supported account types**: Select **Single tenant**
  357. - Click **Register**
  358. 3. Go to the app registration **Overview** and copy:
  359. - **Application (client) ID** — this is your API Client ID for deployment
  360. #### Expose an API (Define a Scope)
  361. 1. In the left menu, go to **Expose an API**
  362. 2. Click **Add** next to **Application ID URI**, and leave it as the default value:
  363. ```
  364. api://<your-client-id>
  365. ```
  366. 3. Click **+ Add a scope**
  367. - **Scope name**: `access`
  368. - **Admin consent display name**: `Access MCP Gateway`
  369. - **Admin consent Description**: Any brief description
  370. - Click **Add scope**
  371. #### Authorize Azure CLI & VS Code as a Client Application
  372. To allow Azure CLI & VS Code to work as the client for token acquisition.
  373. 1. Still in **Expose an API**, scroll down to **Authorized client applications**
  374. 2. Click **+ Add a client application**
  375. - **Client ID**: `04b07795-8ddb-461a-bbee-02f9e1bf7b46` (Azure CLI)
  376. - **Client ID**: `aebc6443-996d-45c2-90f0-388ff96faa56` (VS Code)
  377. - In Authorized scopes, select the scope `access`
  378. - Click **Add**
  379. #### Configure Application Role for Authorization
  380. [docs/entra-app-roles.md](docs/entra-app-roles.md)
  381. ### 3. Deploy Service Resources
  382. For source-change validation, use the checked-out [deployment script](deployment/Deploy-McpGateway.ps1), 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.
  383. 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.
  384. 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](deployment/e2e/README.md#cloud-e2e) for a complete validation sequence.
  385. [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2Fmcp-gateway%2Fmain%2Fdeployment%2Finfra%2Fazure-deployment.json)
  386. **Parameters**
  387. | Name | Description |
  388. |-------------------|------------------------------------------------------------------------------------------------------------------|
  389. | `resourceGroup` | The name of the resource group. Must contain only lowercase letters and numbers (alphanumeric). |
  390. | `clientId` | The Entra ID (Azure AD) client ID from your app registration. |
  391. | `location` | *(Optional)* The Azure region where resources will be deployed.<br/>Defaults to the resource group's location. |
  392. | `resourceLabel` | *(Optional)* A lowercase alphanumeric string used as a suffix for naming resources and as the DNS label.<br/>If not provided, it will be the resourceGroup name.<br/>**Recommendation:** Set this value as the default the same with resource group name and make sure resource group name contains only lower alphanumeric. |
  393. The deployment will:
  394. - Deploy Azure infrastructure via Bicep templates
  395. | Resource Name | Resource Type |
  396. |-------------------------------|-----------------------------|
  397. | mgreg\<resourceLabel> | Container Registry |
  398. | mg-storage-\<resourceLabel> | Azure Cosmos DB Account |
  399. | mg-aag-\<resourceLabel> | Application Gateway |
  400. | mg-ai-\<resourceLabel> | Application Insights |
  401. | mg-aks-\<resourceLabel> | Kubernetes Service (AKS) |
  402. | mg-identity-\<resourceLabel> | Managed Identity |
  403. | mg-pip-\<resourceLabel> | Public IP Address |
  404. | mg-vnet-\<resourceLabel> | Virtual Network |
  405. - Deploy Kubernetes resources (including `mcp-gateway`) to the provisioned AKS cluster
  406. > **Note:** It's recommended to use Managed Identity for credential-less authentication. This deployment follows that design.
  407. ### 4. Build & Publish MCP Server Images
  408. The gateway service pulls the MCP server image from the newly provisioned Azure Container Registry (ACR) during deployment.
  409. Build the MCP server image in ACR:
  410. ```sh
  411. 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"
  412. ```
  413. ### 5. Test the API - MCP Server Management
  414. - Import the OpenAPI spec from `openapi/mcp-gateway.openapi.json` into [Postman](https://www.postman.com/), [Bruno](https://www.usebruno.com/), or [Swagger Editor](https://editor.swagger.io/)
  415. - Acquire a bearer token locally:
  416. ```sh
  417. az account get-access-token --resource $clientId
  418. ```
  419. - Send a POST request to create an adapter resource:
  420. ```http
  421. POST https://<resourceLabel>.<location>.cloudapp.azure.com/adapters
  422. Authorization: Bearer <token>
  423. Content-Type: application/json
  424. ```
  425. ```json
  426. {
  427. "name": "mcp-example",
  428. "imageName": "mcp-example",
  429. "imageVersion": "1.0.0",
  430. "description": "test",
  431. "requiredRoles": [] // Only creator and mcp.admin can access. Add roles (e.g. ["mcp.engineer"]) to grant read access to other principals.
  432. }
  433. ```
  434. ### 6. Test the API - MCP Server Access
  435. - 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).
  436. > **Note:** Ensure VSCode is up to date to access the latest MCP features.
  437. - To connect to the deployed `mcp-example` server, use:
  438. - `https://<resourceLabel>.<location>.cloudapp.azure.com/adapters/mcp-example/mcp` (Streamable HTTP)
  439. Sample `.vscode/mcp.json` that connects to the `mcp-example` server
  440. ```json
  441. {
  442. "servers": {
  443. "mcp-example": {
  444. "url": "https://<resourceLabel>.<location>.cloudapp.azure.com/adapters/mcp-example/mcp",
  445. }
  446. }
  447. }
  448. ```
  449. > **Note:** Authentication is still required to access the MCP server, VS Code will help handle the authentication process.
  450. - For other servers:
  451. - `https://<resourceLabel>.<location>.cloudapp.azure.com/adapters/{name}/mcp` (Streamable HTTP)
  452. ### 7. Test Tool Registration and Dynamic Routing
  453. #### Build & Publish a Tool Server Image
  454. Build and push a tool server image to ACR:
  455. ```sh
  456. 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"
  457. ```
  458. #### Register a Tool
  459. Acquire a bearer token:
  460. ```sh
  461. az account get-access-token --resource $clientId
  462. ```
  463. Send a request to register a tool with its definition:
  464. ```http
  465. POST https://<resourceLabel>.<location>.cloudapp.azure.com/tools
  466. Authorization: Bearer <token>
  467. Content-Type: application/json
  468. ```
  469. ```json
  470. {
  471. "name": "weather",
  472. "imageName": "weather-tool",
  473. "imageVersion": "1.0.0",
  474. "useWorkloadIdentity": true,
  475. "description": "Weather tool for getting current weather information",
  476. "requiredRoles": [], // Only creator and mcp.admin can access. Add roles (e.g. ["mcp.engineer"]) to grant read access to other principals.
  477. "toolDefinition": {
  478. "tool": {
  479. "name": "weather",
  480. "title": "Weather Information",
  481. "description": "Gets the current weather for a specified location.",
  482. "type": "http",
  483. "inputSchema": {
  484. "type": "object",
  485. "properties": {
  486. "location": {
  487. "type": "string",
  488. "description": "The city and state, e.g. San Francisco, CA"
  489. }
  490. },
  491. "required": ["location"]
  492. },
  493. "annotations": {
  494. "readOnly": true
  495. }
  496. },
  497. "port": 8000
  498. }
  499. }
  500. ```
  501. #### Verify Tool Deployment
  502. Check the tool deployment status:
  503. ```http
  504. GET https://<resourceLabel>.<location>.cloudapp.azure.com/tools/weather/status
  505. Authorization: Bearer <token>
  506. ```
  507. #### Test Tool Routing via Tool Gateway Router
  508. Use an MCP client (like VS Code) to connect to the tool gateway router:
  509. Sample `.vscode/mcp.json` that connects to the tool gateway router:
  510. ```json
  511. {
  512. "servers": {
  513. "tool-gateway": {
  514. "url": "https://<resourceLabel>.<location>.cloudapp.azure.com/mcp"
  515. }
  516. }
  517. }
  518. ```
  519. > **Note:** Authentication is required. VS Code will handle the authentication process.
  520. The router will automatically route tool calls to the appropriate registered tool servers based on the tool name in the MCP request.
  521. ### 8. Clean the Environment
  522. To remove all deployed resources, delete the resource group from Azure portal or run:
  523. ```sh
  524. az group delete --name <resourceGroupName> --yes
  525. ```
  526. ### 9. Production Onboarding
  527. - **TLS Configuration**
  528. Set up HTTPS on Azure Application Gateway (AAG) listener using valid TLS certificates.
  529. - **Network Security**
  530. Restrict incoming traffic within the virtual network and configure Private Endpoints for enhanced network security.
  531. - **Service-to-Service Authentication**
  532. The Tool Gateway requires a shared secret (`GatewaySettings:Secret`) to accept forwarded identity headers from the MCP Gateway. In production, generate a strong random value and supply it to both the `mcpgateway` and `toolgateway` pods via the `GatewaySettings__Secret` environment variable or a Kubernetes secret. Requests without a valid `X-Gateway-Secret` header are rejected with `401 Unauthorized`.
  533. - **Telemetry**
  534. Enable advanced telemetry, detailed metrics, and alerts to support monitoring and troubleshooting in production.
  535. - **Scaling**
  536. Adjust scaling for `mcp-gateway` services and MCP servers based on expected load.
  537. - **Authentication & Authorization**
  538. Set up OAuth 2.0 with Azure Entra ID (AAD) for authentication.
  539. Implement fine-grained access control using RBAC or custom ACLs for `adapter` level permissions.
  540. ## Contributing
  541. This project welcomes contributions and suggestions. Most contributions require you to agree to a
  542. Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
  543. the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
  544. When you submit a pull request, a CLA bot will automatically determine whether you need to provide
  545. a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
  546. provided by the bot. You will only need to do this once across all repos using our CLA.
  547. This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
  548. For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
  549. contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
  550. ## Trademarks
  551. This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft
  552. trademarks or logos is subject to and must follow
  553. [Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
  554. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
  555. Any use of third-party trademarks or logos are subject to those third-party's policies.
  556. ## Data Collection
  557. 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.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.