[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-microsoft--mcp-gateway":3,"tool-microsoft--mcp-gateway":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",149489,2,"2026-04-10T11:32:46",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":77,"owner_twitter":78,"owner_website":79,"owner_url":80,"languages":81,"stars":101,"forks":102,"last_commit_at":103,"license":104,"difficulty_score":105,"env_os":106,"env_gpu":107,"env_ram":107,"env_deps":108,"category_tags":115,"github_topics":116,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":134,"updated_at":135,"faqs":136,"releases":166},6349,"microsoft\u002Fmcp-gateway","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.","mcp-gateway 是专为 Model Context Protocol (MCP) 服务器设计的反向代理与管理层，旨在帮助开发者在 Kubernetes 环境中高效构建可扩展的 AI 应用。它主要解决了 MCP 服务在规模化部署时面临的流量路由复杂、会话状态难以保持以及生命周期管理繁琐等痛点。通过提供统一的数据网关和控制平面，mcp-gateway 能够自动处理服务的部署、更新与删除，并确保带有特定会话 ID 的请求始终被精准路由到同一服务器实例，从而维持对话上下文的连贯性。\n\n这款工具特别适合需要在生产环境中部署多租户 AI 代理平台的后端工程师、DevOps 专家及架构师。其核心技术亮点在于“会话感知的有状态路由”机制，这在无状态的云原生环境中尤为珍贵，能有效保障复杂交互场景下的稳定性。此外，mcp-gateway 还内置了企业级的身份验证、访问控制及可观测性接口，支持与现有监控体系无缝集成。无论是管理单一的 MCP 服务，还是协调成百上千个动态工具节点，mcp-gateway 都能提供清晰的管理视图和稳健的运行支撑，让团队更专注于业务逻辑而非基础设施运维。","# MCP Gateway\n\n**MCP Gateway** is a reverse proxy and management layer for [Model Context Protocol (MCP)](https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction) servers, enabling scalable, session-aware routing, authorization and lifecycle management of MCP servers in Kubernetes environments.\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Key Concepts](#key-concepts)\n- [Architecture](#architecture)\n- [Features](#features)\n- [Getting Started – Local Deployment](#getting-started---local-deployment)\n- [Getting Started – 1-Click Deploy to Azure](#getting-started---deploy-to-azure)\n\n## Overview\n\nThis project provides:\n\n- A data gateway for routing traffic to MCP servers with session affinity.\n- A control plane for managing the MCP server lifecycle (deploy, update, delete).\n- Enterprise-ready integration points including telemetry, access control and observability.\n\n## Key Concepts\n\n- **MCP Server**: A server implementing the Model Context Protocol, which typically a streamable HTTP endpoint.\n- **Adapters**: Logical resources representing MCP servers in the gateway, managed under the `\u002Fadapters` scope. Designed to coexist with other resource types (e.g., `\u002Fagents`) in a unified AI development platform.\n- **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.\n- **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.\n- **Session-Aware Stateful Routing**: Ensures that all requests with a given `session_id` are consistently routed to the same MCP server instance.\n\n## Architecture\n\n```mermaid\nflowchart LR\n    subgraph Clients[\" \"]\n        direction TB\n        DataClient[\"🔌 Agent\u002FMCP\u003Cbr>Data Client\"]\n        MgmtClient[\"⚙️ Management\u003Cbr>Client\"]\n    end\n\n    subgraph Gateway[\"MCP Gateway\"]\n        direction TB\n        \n        subgraph Auth1[\"Authentication & Authorization\"]\n            Auth[\"🔐 Data Plane Auth\u003Cbr>Bearer Token \u002F RBAC\"]\n            Auth2[\"🔐 Control Plane Auth\u003Cbr>Bearer Token \u002F RBAC\"]\n        end\n        \n        subgraph DataPlane[\"Data Plane\"]\n            Routing[\"🔀 Adapter Routing\u003Cbr>\u002Fadapters\u002F{name}\u002Fmcp\"]\n            ToolRouting[\"🔀 Tool Router Gateway\u003Cbr>\u002Fmcp\"]\n        end\n\n        subgraph ControlPlane[\"Control Plane\"]\n            direction LR\n            AdapterMgmt[\"📦 Adapter Management\u003Cbr>\u002Fadapters CRUD\"]\n            ToolMgmt[\"🔧 Tool Management\u003Cbr>\u002Ftools CRUD\"]\n        end\n        \n        subgraph Management[\"Backend Services\"]\n            DeploymentMgmt[\"☸️ Deployment Manager\"]\n            MetadataMgmt[\"📋 Metadata Manager\"]\n        end\n    end\n\n    subgraph Cluster[\"Kubernetes Cluster\"]\n        direction TB\n        \n        subgraph ServerRow[\" \"]\n            direction LR\n            \n            subgraph MCPServers[\"MCP Servers\"]\n                direction TB\n                PodA[\"mcp-a-0\"]\n                PodA1[\"mcp-a-1\"]\n                PodB[\"mcp-b-0\"]\n            end\n            \n            subgraph ToolRouters[\"Tool Gateway Routers\"]\n                direction TB\n                Router1[\"toolgateway-0\"]\n                Router2[\"toolgateway-1\"]\n            end\n        end\n        \n        subgraph ToolServers[\"Registered Tool Servers\"]\n            direction LR\n            Tool1[\"tool-1-0\"]\n            Tool2[\"tool-2-0\"]\n        end\n    end\n\n    Metadata[(\"💾 Metadata Store\u003Cbr>Server & Tool Info\")]\n\n    DataClient -->|\"MCP Requests\"| Auth\n    MgmtClient -->|\"API Calls\"| Auth2\n    \n    Auth --> Routing\n    Auth --> ToolRouting\n    Auth2 --> AdapterMgmt\n    Auth2 --> ToolMgmt\n    \n    AdapterMgmt & ToolMgmt --> DeploymentMgmt\n    AdapterMgmt & ToolMgmt --> MetadataMgmt\n    \n    Routing -.->|\"Session Affinity\"| MCPServers\n    ToolRouting -.->|\"Session Affinity\"| ToolRouters\n    ToolRouters ==>|\"Dynamic Routing\"| ToolServers\n    \n    DeploymentMgmt -->|\"Deploy & Monitor\"| Cluster\n    MetadataMgmt \u003C-->|\"Read\u002FWrite\"| Metadata\n\n    style Gateway fill:#e1f5ff\n    style Cluster fill:#fff4e1\n    style Metadata fill:#f0f0f0\n```\n\n## Features\n\n### Control Plane – RESTful APIs for MCP Server Management\n\n#### MCP Server Management (Adapters)\n\n- `POST \u002Fadapters` — Deploy and register a new MCP server.\n- `GET \u002Fadapters` — List all MCP servers the user can access.\n- `GET \u002Fadapters\u002F{name}` — Retrieve metadata for a specific adapter.\n- `GET \u002Fadapters\u002F{name}\u002Fstatus` — Check the deployment status.\n- `GET \u002Fadapters\u002F{name}\u002Flogs` — Access the server's running logs.\n- `PUT \u002Fadapters\u002F{name}` — Update the deployment.\n- `DELETE \u002Fadapters\u002F{name}` — Remove the server.\n\n#### Tool Registration and Management\n\n- `POST \u002Ftools` — Register and deploy a tool with MCP tool definition metadata.\n- `GET \u002Ftools` — List all registered tools the user can access.\n- `GET \u002Ftools\u002F{name}` — Retrieve metadata and tool definition for a specific tool.\n- `GET \u002Ftools\u002F{name}\u002Fstatus` — Check the tool deployment status.\n- `GET \u002Ftools\u002F{name}\u002Flogs` — Access the tool server's running logs.\n- `PUT \u002Ftools\u002F{name}` — Update a tool deployment and definition.\n- `DELETE \u002Ftools\u002F{name}` — Remove a registered tool.\n\n### Data Plane – Gateway Routing for MCP Servers\n\n#### Direct MCP Server Access\n\n- `POST \u002Fadapters\u002F{name}\u002Fmcp` — Establish a streamable HTTP connection.\n\n#### Dynamic Tool Routing via Tool Gateway Router\n\n- `POST \u002Fmcp` — 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.\n\n### Authentication & Authorization Support\n\nThe gateway provides entra id authentication and basic application role authorization for mcp servers and tools:\n\n- **Read** access is granted to the resource creator, principals assigned the configured role values (for example `mcp.engineer`), and anyone holding the mandatory administrator role `mcp.admin`.\n- **Write** access is restricted to the resource creator or principals holding the `mcp.admin` role.\n\nFor 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\u002Ftool payloads), see [docs\u002Fentra-app-roles.md](docs\u002Fentra-app-roles.md).\n\n### Additional Capabilities\n\n- *New*: Support for **Proxying Local & Remote MCP Servers**. See [examples and usage](sample-servers\u002Fmcp-proxy\u002FREADME.md).\n- Stateless reverse proxy with a distributed session store (production mode).\n- Kubernetes-native deployment using StatefulSets and headless services.\n\n### Tool Registration and Dynamic Routing\n\nThe MCP Gateway now supports **tool registration** with dynamic routing capabilities, enabling a scalable architecture for managing and executing MCP tools.\n\n### How It Works\n\n1. **Tool Registration**: Developers register tools via the `\u002Ftools` API endpoint, providing:\n   - Container image details (name and version)\n   - MCP tool definition (name, description, input schema)\n   - Execution endpoint configuration (port and path)\n   - Deployment configuration (replicas, environment variables)\n\n2. **Tool Gateway Router**: A specialized MCP server that acts as an intelligent router:\n   - Runs as multiple instances behind the gateway for high availability\n   - Maintains awareness of all registered tools and their definitions\n   - Dynamically routes tool execution requests to the appropriate tool server\n   - Accessed via `POST \u002Fmcp` endpoint (without adapter name)\n\n3. **Dynamic Routing**: When clients send MCP requests to `\u002Fmcp`:\n   - The gateway routes requests to available tool gateway router instances with session affinity\n   - The router analyzes the tool call in the request\n   - Based on the tool definition, it forwards the execution to the correct registered tool server\n   - Results are returned through the router back to the client\n\n## Getting Started - Local Deployment\n\n### 1. Prepare Local Development Environment\n- [Install .NET 8 SDK](https:\u002F\u002Fdotnet.microsoft.com\u002Fen-us\u002Fdownload\u002Fdotnet\u002F8.0)\n- [Install Docker Desktop](https:\u002F\u002Fdocs.docker.com\u002Fdesktop\u002F)\n- [Install and turn on Kubernetes](https:\u002F\u002Fdocs.docker.com\u002Fdesktop\u002Ffeatures\u002Fkubernetes\u002F#install-and-turn-on-kubernetes)\n\n### 2. Run Local Docker Registry\n   ```sh\n   docker run -d -p 5000:5000 --name registry registry:2.7\n   ```\n\n### 3. Build & Publish MCP Server Images\nBuild and push the MCP server images to your local registry (`localhost:5000`).\n```sh\ndocker build -f sample-servers\u002Fmcp-example\u002FDockerfile sample-servers\u002Fmcp-example -t localhost:5000\u002Fmcp-example:1.0.0\ndocker push localhost:5000\u002Fmcp-example:1.0.0\n```\n\n### 4. Build & Publish MCP Gateway and Tool Gateway Router\n(Optional) Open `dotnet\u002FMicrosoft.McpGateway.sln` with Visual Studio.\n\nPublish the MCP Gateway image:\n```sh\ndotnet publish dotnet\u002FMicrosoft.McpGateway.Service\u002Fsrc\u002FMicrosoft.McpGateway.Service.csproj -c Release \u002Fp:PublishProfile=localhost_5000.pubxml\n```\n\nPublish the Tool Gateway Router image:\n```sh\ndotnet publish dotnet\u002FMicrosoft.McpGateway.Tools\u002Fsrc\u002FMicrosoft.McpGateway.Tools.csproj -c Release \u002Fp:PublishProfile=localhost_5000.pubxml\n```\n\n### 5. Deploy MCP Gateway to Kubernetes Cluster\nApply the deployment manifests:\n```sh\nkubectl apply -f deployment\u002Fk8s\u002Flocal-deployment.yml\n```\n\n### 6. Enable Port Forwarding\nForward the gateway service port:\n```sh\nkubectl port-forward -n adapter svc\u002Fmcpgateway-service 8000:8000\n```\n\n### 7. Test the API - MCP Server Management\n- Import the OpenAPI definition from `openapi\u002Fmcp-gateway.openapi.json` into tools like [Postman](https:\u002F\u002Fwww.postman.com\u002F), [Bruno](https:\u002F\u002Fwww.usebruno.com\u002F), or [Swagger Editor](https:\u002F\u002Feditor.swagger.io\u002F).\n\n- Send a request to create a new adapter resource:\n  ```http\n  POST http:\u002F\u002Flocalhost:8000\u002Fadapters\n  Content-Type: application\u002Fjson\n  ```\n   ```json\n   {\n      \"name\": \"mcp-example\",\n      \"imageName\": \"mcp-example\",\n      \"imageVersion\": \"1.0.0\",\n      \"description\": \"test\"\n   }\n   ```\n\n### 8. Test the API - MCP Server Access \n- After deploying the MCP server, use a client like [VS Code](https:\u002F\u002Fcode.visualstudio.com\u002F) to test the connection. Refer to the guide: [Use MCP servers in VS Code](https:\u002F\u002Fcode.visualstudio.com\u002Fdocs\u002Fcopilot\u002Fchat\u002Fmcp-servers). \n  > **Note:** Ensure VSCode is up to date to access the latest MCP features.\n\n  - To connect to the deployed `mcp-example` server, use:  \n     - `http:\u002F\u002Flocalhost:8000\u002Fadapters\u002Fmcp-example\u002Fmcp` (Streamable HTTP)\n\n  Sample `.vscode\u002Fmcp.json` that connects to the `mcp-example` server\n  ```json\n  {\n    \"servers\": {\n      \"mcp-example\": {\n        \"url\": \"http:\u002F\u002Flocalhost:8000\u002Fadapters\u002Fmcp-example\u002Fmcp\",\n      }\n    }\n  }\n  ```\n\n- For other servers:  \n  - `http:\u002F\u002Flocalhost:8000\u002Fadapters\u002F{name}\u002Fmcp` (Streamable HTTP)  \n\n### 9. Test Tool Registration and Dynamic Routing\n\n#### Build & Publish a Tool Server Image\n\nFirst, build and push a tool server image to your local registry:\n```sh\ndocker build -f sample-servers\u002Ftool-example\u002FDockerfile sample-servers\u002Ftool-example -t localhost:5000\u002Fweather-tool:1.0.0\ndocker push localhost:5000\u002Fweather-tool:1.0.0\n```\n\n#### Register a Tool\n\nSend a request to register a tool with its definition:\n```http\nPOST http:\u002F\u002Flocalhost:8000\u002Ftools\nContent-Type: application\u002Fjson\n```\n```json\n{\n  \"name\": \"weather\",\n  \"imageName\": \"weather-tool\",\n  \"imageVersion\": \"1.0.0\",\n  \"description\": \"Weather tool for getting current weather information\",\n  \"toolDefinition\": {\n    \"tool\": {\n      \"name\": \"weather\",\n      \"title\": \"Weather Information\",\n      \"description\": \"Gets the current weather for a specified location.\",\n      \"type\": \"http\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"location\": {\n            \"type\": \"string\",\n            \"description\": \"The city and state, e.g. San Francisco, CA\"\n          }\n        },\n        \"required\": [\"location\"]\n      }\n    },\n    \"port\": 8000\n  }\n}\n```\n\n#### Verify Tool Deployment\n\nCheck the tool deployment status:\n```http\nGET http:\u002F\u002Flocalhost:8000\u002Ftools\u002Fweather\u002Fstatus\n```\n\n#### Test Tool Routing via Tool Gateway Router\n\nUse an MCP client (like VS Code) to connect to the tool gateway router:\n\nSample `.vscode\u002Fmcp.json` that connects to the tool gateway router:\n```json\n{\n  \"servers\": {\n    \"tool-gateway\": {\n      \"url\": \"http:\u002F\u002Flocalhost:8000\u002Fmcp\"\n    }\n  }\n}\n```\n\nThe router will automatically route tool calls to the appropriate registered tool servers based on the tool name in the MCP request.\n\n### 10. Clean the Environment  \n   To remove all deployed resources, delete the Kubernetes namespace:\n   ```sh\n   kubectl delete namespace adapter\n   ```\n\n## Getting Started - Deploy to Azure\n\n### Cloud Infrastructure\n![Architecture Diagram](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmicrosoft_mcp-gateway_readme_5191cfb08cff.png)\n\n### 1. Prepare Cloud Development Environment\n- An active [Azure subscription](https:\u002F\u002Fazure.microsoft.com) with **Owner** access\n- [Install Azure CLI](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fcli\u002Fazure\u002Finstall-azure-cli)\n\n### 2. Setup Entra ID (Azure Active Directory)\n\nThe cloud-deployed service requires bearer token authentication using Azure Entra ID. Follow these steps to configure an app registration.\n\n#### Create and Configure the App Registration\n\n1. Go to [App Registrations](https:\u002F\u002Fportal.azure.com\u002F#view\u002FMicrosoft_AAD_RegisteredApps\u002FApplicationsListBlade)\n2. Click **+ New registration**\n   - **Name**: Choose a meaningful name, e.g., `mcp-gateway`\n   - **Supported account types**: Select **Single tenant**\n   - Click **Register**\n\n3. Go to the app registration **Overview** and copy:\n   - **Application (client) ID** — this is your API Client ID for deployment\n\n#### Expose an API (Define a Scope)\n\n1. In the left menu, go to **Expose an API**\n2. Click **Add** next to **Application ID URI**, and leave it as the default value:\n   ```\n   api:\u002F\u002F\u003Cyour-client-id>\n   ```\n\n3. Click **+ Add a scope**\n   - **Scope name**: `access`\n   - **Admin consent display name**: `Access MCP Gateway`\n   - **Admin consent Description**: Any brief description\n   - Click **Add scope**\n\n#### Authorize Azure CLI & VS Code as a Client Application\n\nTo allow Azure CLI & VS Code to work as the client for token acquisition.\n\n1. Still in **Expose an API**, scroll down to **Authorized client applications**\n2. Click **+ Add a client application**\n   - **Client ID**: `04b07795-8ddb-461a-bbee-02f9e1bf7b46` (Azure CLI)\n   - **Client ID**: `aebc6443-996d-45c2-90f0-388ff96faa56` (VS Code)\n   - In Authorized scopes, select the scope `access`\n   - Click **Add**\n\n#### Configure Application Role for Authorization\n[docs\u002Fentra-app-roles.md](docs\u002Fentra-app-roles.md)\n\n### 3. Deploy Service Resources\n\n[![Deploy to Azure](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmicrosoft_mcp-gateway_readme_7343390a6970.png)](https:\u002F\u002Fportal.azure.com\u002F#create\u002FMicrosoft.Template\u002Furi\u002Fhttps%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2Fmcp-gateway%2Fmain%2Fdeployment%2Finfra%2Fazure-deployment.json)\n\n**Parameters**\n| Name              | Description                                                                                                      |\n|-------------------|------------------------------------------------------------------------------------------------------------------|\n| `resourceGroup`   | The name of the resource group. Must contain only lowercase letters and numbers (alphanumeric).                 |\n| `clientId`        | The Entra ID (Azure AD) client ID from your app registration.                                                    |\n| `location`        | *(Optional)* The Azure region where resources will be deployed.\u003Cbr\u002F>Defaults to the resource group's location.   |\n| `resourceLabel`   | *(Optional)* A lowercase alphanumeric string used as a suffix for naming resources and as the DNS label.\u003Cbr\u002F>If not provided, it will be the resourceGroup name.\u003Cbr\u002F>**Recommendation:** Set this value as the default the same with resource group name and make sure resource group name contains only lower alphanumeric. |\n\n\nThe deployment will:\n- Deploy Azure infrastructure via Bicep templates\n\n   | Resource Name                 | Resource Type               |\n   |-------------------------------|-----------------------------|\n   | mgreg\\\u003CresourceLabel>         | Container Registry          |\n   | mg-storage-\\\u003CresourceLabel>   | Azure Cosmos DB Account     |\n   | mg-aag-\\\u003CresourceLabel>       | Application Gateway         |\n   | mg-ai-\\\u003CresourceLabel>        | Application Insights        |\n   | mg-aks-\\\u003CresourceLabel>       | Kubernetes Service (AKS)    |\n   | mg-identity-\\\u003CresourceLabel>  | Managed Identity            |\n   | mg-pip-\\\u003CresourceLabel>       | Public IP Address           |\n   | mg-vnet-\\\u003CresourceLabel>      | Virtual Network             |\n\n- Deploy Kubernetes resources (including `mcp-gateway`) to the provisioned AKS cluster\n\n> **Note:** It's recommended to use Managed Identity for credential-less authentication. This deployment follows that design.\n\n### 4. Build & Publish MCP Server Images\nThe gateway service pulls the MCP server image from the newly provisioned Azure Container Registry (ACR) during deployment.\n\nBuild the MCP server image in ACR:\n\n```sh\naz acr build -r \"mgreg$resourceLabel\" -f sample-servers\u002Fmcp-example\u002FDockerfile sample-servers\u002Fmcp-example -t \"mgreg$resourceLabel.azurecr.io\u002Fmcp-example:1.0.0\"\n```\n\n### 5. Test the API - MCP Server Management\n\n- Import the OpenAPI spec from `openapi\u002Fmcp-gateway.openapi.json` into [Postman](https:\u002F\u002Fwww.postman.com\u002F), [Bruno](https:\u002F\u002Fwww.usebruno.com\u002F), or [Swagger Editor](https:\u002F\u002Feditor.swagger.io\u002F)\n\n- Acquire a bearer token locally:\n  ```sh\n  az account get-access-token --resource $clientId\n  ```\n\n- Send a POST request to create an adapter resource:\n  ```http\n  POST http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Fadapters\n  Authorization: Bearer \u003Ctoken>\n  Content-Type: application\u002Fjson\n  ```\n  ```json\n  {\n    \"name\": \"mcp-example\",\n    \"imageName\": \"mcp-example\",\n    \"imageVersion\": \"1.0.0\",\n    \"description\": \"test\",\n    \"requiredRoles\": [] \u002F\u002F Add entra id application role to restrict access\n  }\n  ```\n\n### 6. Test the API - MCP Server Access\n\n- After deploying the MCP server, use a client like [VS Code](https:\u002F\u002Fcode.visualstudio.com\u002F) to test the connection. Refer to the guide: [Use MCP servers in VS Code](https:\u002F\u002Fcode.visualstudio.com\u002Fdocs\u002Fcopilot\u002Fchat\u002Fmcp-servers). \n  > **Note:** Ensure VSCode is up to date to access the latest MCP features.\n\n  - To connect to the deployed `mcp-example` server, use:  \n     - `http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Fadapters\u002Fmcp-example\u002Fmcp` (Streamable HTTP)\n\n  Sample `.vscode\u002Fmcp.json` that connects to the `mcp-example` server\n  ```json\n  {\n    \"servers\": {\n      \"mcp-example\": {\n        \"url\": \"http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Fadapters\u002Fmcp-example\u002Fmcp\",\n      }\n    }\n  }\n  ```\n  > **Note:** Authentication is still required to access the MCP server, VS Code will help handle the authentication process.\n\n- For other servers:  \n  - `http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Fadapters\u002F{name}\u002Fmcp` (Streamable HTTP)  \n\n### 7. Test Tool Registration and Dynamic Routing\n\n#### Build & Publish a Tool Server Image\n\nBuild and push a tool server image to ACR:\n```sh\naz acr build -r \"mgreg$resourceLabel\" -f sample-servers\u002Ftool-example\u002FDockerfile sample-servers\u002Ftool-example -t \"mgreg$resourceLabel.azurecr.io\u002Fweather-tool:1.0.0\"\n```\n\n#### Register a Tool\n\nAcquire a bearer token:\n```sh\naz account get-access-token --resource $clientId\n```\n\nSend a request to register a tool with its definition:\n```http\nPOST http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Ftools\nAuthorization: Bearer \u003Ctoken>\nContent-Type: application\u002Fjson\n```\n```json\n{\n  \"name\": \"weather\",\n  \"imageName\": \"weather-tool\",\n  \"imageVersion\": \"1.0.0\",\n  \"useWorkloadIdentity\": true,\n  \"description\": \"Weather tool for getting current weather information\",\n  \"requiredRoles\": [], \u002F\u002F Add entra id application role to restrict access\n  \"toolDefinition\": {\n    \"tool\": {\n      \"name\": \"weather\",\n      \"title\": \"Weather Information\",\n      \"description\": \"Gets the current weather for a specified location.\",\n      \"type\": \"http\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"location\": {\n            \"type\": \"string\",\n            \"description\": \"The city and state, e.g. San Francisco, CA\"\n          }\n        },\n        \"required\": [\"location\"]\n      },\n      \"annotations\": {\n        \"readOnly\": true\n      }\n    },\n    \"port\": 8000\n  }\n}\n```\n\n#### Verify Tool Deployment\n\nCheck the tool deployment status:\n```http\nGET http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Ftools\u002Fweather\u002Fstatus\nAuthorization: Bearer \u003Ctoken>\n```\n\n#### Test Tool Routing via Tool Gateway Router\n\nUse an MCP client (like VS Code) to connect to the tool gateway router:\n\nSample `.vscode\u002Fmcp.json` that connects to the tool gateway router:\n```json\n{\n  \"servers\": {\n    \"tool-gateway\": {\n      \"url\": \"http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Fmcp\"\n    }\n  }\n}\n```\n> **Note:** Authentication is required. VS Code will handle the authentication process.\n\nThe router will automatically route tool calls to the appropriate registered tool servers based on the tool name in the MCP request.\n\n### 8. Clean the Environment\nTo remove all deployed resources, delete the resource group from Azure portal or run:\n```sh\naz group delete --name \u003CresourceGroupName> --yes\n```\n\n### 9. Production Onboarding\n\n- **TLS Configuration**  \n  Set up HTTPS on Azure Application Gateway (AAG) listener using valid TLS certificates.\n\n- **Network Security**  \n  Restrict incoming traffic within the virtual network and configure Private Endpoints for enhanced network security.\n\n- **Telemetry**  \n  Enable advanced telemetry, detailed metrics, and alerts to support monitoring and troubleshooting in production.\n\n- **Scaling**  \n  Adjust scaling for `mcp-gateway` services and MCP servers based on expected load.\n\n- **Authentication & Authorization**  \n  Set up OAuth 2.0 with Azure Entra ID (AAD) for authentication.\n  Implement fine-grained access control using RBAC or custom ACLs for `adapter` level permissions.\n\n## Contributing\n\nThis project welcomes contributions and suggestions.  Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit https:\u002F\u002Fcla.opensource.microsoft.com.\n\nWhen you submit a pull request, a CLA bot will automatically determine whether you need to provide\na CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions\nprovided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https:\u002F\u002Fopensource.microsoft.com\u002Fcodeofconduct\u002F).\nFor more information see the [Code of Conduct FAQ](https:\u002F\u002Fopensource.microsoft.com\u002Fcodeofconduct\u002Ffaq\u002F) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n\n## Trademarks\n\nThis project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft \ntrademarks or logos is subject to and must follow \n[Microsoft's Trademark & Brand Guidelines](https:\u002F\u002Fwww.microsoft.com\u002Fen-us\u002Flegal\u002Fintellectualproperty\u002Ftrademarks\u002Fusage\u002Fgeneral).\nUse of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.\nAny use of third-party trademarks or logos are subject to those third-party's policies.\n\n## Data Collection\n\nThe 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:\u002F\u002Fgo.microsoft.com\u002Ffwlink\u002F?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.\n","# MCP 网关\n\n**MCP 网关** 是 [模型上下文协议 (MCP)](https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction) 服务器的反向代理和管理层，能够在 Kubernetes 环境中实现可扩展的、基于会话感知的路由、授权以及 MCP 服务器的生命周期管理。\n\n## 目录\n\n- [概述](#overview)\n- [关键概念](#key-concepts)\n- [架构](#architecture)\n- [特性](#features)\n- [快速入门 – 本地部署](#getting-started---local-deployment)\n- [快速入门 – 一键部署至 Azure](#getting-started---deploy-to-azure)\n\n## 概述\n\n本项目提供：\n\n- 用于将流量路由到具有会话亲和性的 MCP 服务器的数据网关。\n- 用于管理 MCP 服务器生命周期（部署、更新、删除）的控制平面。\n- 企业级集成点，包括遥测、访问控制和可观性。\n\n## 关键概念\n\n- **MCP 服务器**：实现模型上下文协议的服务器，通常是一个可流式传输的 HTTP 端点。\n- **适配器**：在网关中表示 MCP 服务器的逻辑资源，在 `\u002Fadapters` 范围内进行管理。设计用于与其他资源类型（例如 `\u002Fagents`）共存于统一的人工智能开发平台中。\n- **工具**：注册了 MCP 工具定义的资源，可通过工具网关路由器动态路由。每个工具都包含有关其执行端点和输入模式的元数据。\n- **工具网关路由器**：作为智能路由器的 MCP 服务器，根据工具定义将工具执行请求定向到适当的已注册工具服务器。为了实现会话亲和性，网关后方可以运行多个路由器实例。\n- **基于会话的状态感知路由**：确保具有给定 `session_id` 的所有请求始终路由到同一 MCP 服务器实例。\n\n## 架构\n\n```mermaid\nflowchart LR\n    subgraph 客户端[\" \"]\n        direction TB\n        数据客户端[\"🔌 代理\u002FMCP\u003Cbr>数据客户端\"]\n        管理客户端[\"⚙️ 管理\u003Cbr>客户端\"]\n    end\n\n    subgraph 网关[\"MCP 网关\"]\n        direction TB\n        \n        subgraph 认证1[\"身份验证与授权\"]\n            认证[\"🔐 数据平面认证\u003Cbr>Bearer Token \u002F RBAC\"]\n            认证2[\"🔐 控制平面认证\u003Cbr>Bearer Token \u002F RBAC\"]\n        end\n        \n        subgraph 数据平面[\"数据平面\"]\n            路由[\"🔀 适配器路由\u003Cbr>\u002Fadapters\u002F{name}\u002Fmcp\"]\n            工具路由[\"🔀 工具网关路由器\u003Cbr>\u002Fmcp\"]\n        end\n\n        subgraph 控制平面[\"控制平面\"]\n            direction LR\n            适配器管理[\"📦 适配器管理\u003Cbr>\u002Fadapters CRUD\"]\n            工具管理[\"🔧 工具管理\u003Cbr>\u002Ftools CRUD\"]\n        end\n        \n        subgraph 管理[\"后台服务\"]\n            部署管理[\"☸️ 部署管理器\"]\n            元数据管理[\"📋 元数据管理器\"]\n        end\n    end\n\n    subgraph 集群[\"Kubernetes 集群\"]\n        direction TB\n        \n        subgraph 服务器行[\" \"]\n            direction LR\n            \n            subgraph MCP服务器[\"MCP 服务器\"]\n                direction TB\n                PodA[\"mcp-a-0\"]\n                PodA1[\"mcp-a-1\"]\n                PodB[\"mcp-b-0\"]\n            end\n            \n            subgraph 工具路由器[\"工具网关路由器\"]\n                direction TB\n                Router1[\"toolgateway-0\"]\n                Router2[\"toolgateway-1\"]\n            end\n        end\n        \n        subgraph 工具服务器[\"已注册工具服务器\"]\n            direction LR\n            Tool1[\"tool-1-0\"]\n            Tool2[\"tool-2-0\"]\n        end\n    end\n\n    元数据[(\"💾 元数据存储\u003Cbr>服务器与工具信息\")]\n\n    数据客户端 -->|\"MCP 请求\"| 认证\n    管理客户端 -->|\"API 调用\"| 认证2\n    \n    认证 --> 路由\n    认证 --> 工具路由\n    认证2 --> 适配器管理\n    认证2 --> 工具管理\n    \n    适配器管理 & 工具管理 --> 部署管理\n    适配器管理 & 工具管理 --> 元数据管理\n    \n    路由 -.->|\"会话亲和性\"| MCP服务器\n    工具路由 -.->|\"会话亲和性\"| 工具路由器\n    工具路由器 ==>|\"动态路由\"| 工具服务器\n    \n    部署管理 -->|\"部署 & 监控\"| 集群\n    元数据管理 \u003C-->|\"读\u002F写\"| 元数据\n\n    style 网关 fill:#e1f5ff\n    style 集群 fill:#fff4e1\n    style 元数据 fill:#f0f0f0\n```\n\n## 特性\n\n### 控制平面 – 用于 MCP 服务器管理的 RESTful API\n\n#### MCP 服务器管理（适配器）\n\n- `POST \u002Fadapters` — 部署并注册一个新的 MCP 服务器。\n- `GET \u002Fadapters` — 列出用户可访问的所有 MCP 服务器。\n- `GET \u002Fadapters\u002F{name}` — 获取特定适配器的元数据。\n- `GET \u002Fadapters\u002F{name}\u002Fstatus` — 检查部署状态。\n- `GET \u002Fadapters\u002F{name}\u002Flogs` — 访问服务器的运行日志。\n- `PUT \u002Fadapters\u002F{name}` — 更新部署。\n- `DELETE \u002Fadapters\u002F{name}` — 删除服务器。\n\n#### 工具注册与管理\n\n- `POST \u002Ftools` — 注册并部署一个带有 MCP 工具定义元数据的工具。\n- `GET \u002Ftools` — 列出用户可访问的所有已注册工具。\n- `GET \u002Ftools\u002F{name}` — 获取特定工具的元数据和工具定义。\n- `GET \u002Ftools\u002F{name}\u002Fstatus` — 检查工具部署状态。\n- `GET \u002Ftools\u002F{name}\u002Flogs` — 访问工具服务器的运行日志。\n- `PUT \u002Ftools\u002F{name}` — 更新工具的部署和定义。\n- `DELETE \u002Ftools\u002F{name}` — 删除已注册的工具。\n\n### 数据平面 – MCP 服务器的网关路由\n\n#### 直接访问 MCP 服务器\n\n- `POST \u002Fadapters\u002F{name}\u002Fmcp` — 建立可流式传输的 HTTP 连接。\n\n#### 通过工具网关路由器的动态工具路由\n\n- `POST \u002Fmcp` — 将请求路由到工具网关路由器，该路由器会根据工具定义动态路由到已注册的工具。路由器本身是 MCP 服务器，网关后方托管了多个实例以实现可扩展性。\n\n### 身份验证与授权支持\n\n网关为 MCP 服务器和工具提供 Entra ID 身份验证以及基本的应用程序角色授权：\n\n- **读取**权限授予资源创建者、被分配了配置角色值（例如 `mcp.engineer`）的主体，以及持有强制性管理员角色 `mcp.admin` 的任何人。\n- **写入**权限仅限于资源创建者或持有 `mcp.admin` 角色的主体。\n\n有关配置 Azure Entra ID（创建 `mcp.admin` 和其他角色值、将其分配给用户或服务主体，并在适配器\u002F工具负载中提供这些值）的分步指南，请参阅 [docs\u002Fentra-app-roles.md](docs\u002Fentra-app-roles.md)。\n\n### 其他功能\n\n- *新增*：支持 **代理本地及远程 MCP 服务器**。请参阅 [示例与使用方法](sample-servers\u002Fmcp-proxy\u002FREADME.md)。\n- 带有分布式会话存储的状态无感知反向代理（生产模式）。\n- 使用 StatefulSets 和 Headless Services 的 Kubernetes 原生部署。\n\n### 工具注册与动态路由\n\nMCP 网关现在支持 **工具注册** 及其动态路由功能，从而实现管理和执行 MCP 工具的可扩展架构。\n\n### 工作原理\n\n1. **工具注册**：开发者通过 `\u002Ftools` API 端点注册工具，需提供：\n   - 容器镜像详情（名称和版本）\n   - MCP 工具定义（名称、描述、输入模式）\n   - 执行端点配置（端口和路径）\n   - 部署配置（副本数、环境变量）\n\n2. **工具网关路由器**：一个作为智能路由的专用 MCP 服务器：\n   - 在网关后以多个实例运行，确保高可用性\n   - 维护所有已注册工具及其定义的实时信息\n   - 动态将工具执行请求路由到相应的工具服务器\n   - 通过 `POST \u002Fmcp` 端点访问（无需指定适配器名称）\n\n3. **动态路由**：当客户端向 `\u002Fmcp` 发送 MCP 请求时：\n   - 网关会将请求以会话亲和性路由到可用的工具网关路由器实例\n   - 路由器会分析请求中的工具调用信息\n   - 根据工具定义，将执行请求转发到正确的已注册工具服务器\n   - 执行结果通过路由器返回给客户端\n\n## 快速入门 - 本地部署\n\n### 1. 准备本地开发环境\n- [安装 .NET 8 SDK](https:\u002F\u002Fdotnet.microsoft.com\u002Fen-us\u002Fdownload\u002Fdotnet\u002F8.0)\n- [安装 Docker Desktop](https:\u002F\u002Fdocs.docker.com\u002Fdesktop\u002F)\n- [安装并启用 Kubernetes](https:\u002F\u002Fdocs.docker.com\u002Fdesktop\u002Ffeatures\u002Fkubernetes\u002F#install-and-turn-on-kubernetes)\n\n### 2. 运行本地 Docker 注册表\n   ```sh\n   docker run -d -p 5000:5000 --name registry registry:2.7\n   ```\n\n### 3. 构建并发布 MCP 服务器镜像\n将 MCP 服务器镜像构建并推送到本地注册表（`localhost:5000`）。\n```sh\ndocker build -f sample-servers\u002Fmcp-example\u002FDockerfile sample-servers\u002Fmcp-example -t localhost:5000\u002Fmcp-example:1.0.0\ndocker push localhost:5000\u002Fmcp-example:1.0.0\n```\n\n### 4. 构建并发布 MCP 网关和工具网关路由器\n（可选）使用 Visual Studio 打开 `dotnet\u002FMicrosoft.McpGateway.sln`。\n\n发布 MCP 网关镜像：\n```sh\ndotnet publish dotnet\u002FMicrosoft.McpGateway.Service\u002Fsrc\u002FMicrosoft.McpGateway.Service.csproj -c Release \u002Fp:PublishProfile=localhost_5000.pubxml\n```\n\n发布工具网关路由器镜像：\n```sh\ndotnet publish dotnet\u002FMicrosoft.McpGateway.Tools\u002Fsrc\u002FMicrosoft.McpGateway.Tools.csproj -c Release \u002Fp:PublishProfile=localhost_5000.pubxml\n```\n\n### 5. 将 MCP 网关部署到 Kubernetes 集群\n应用部署清单文件：\n```sh\nkubectl apply -f deployment\u002Fk8s\u002Flocal-deployment.yml\n```\n\n### 6. 启用端口转发\n转发网关服务端口：\n```sh\nkubectl port-forward -n adapter svc\u002Fmcpgateway-service 8000:8000\n```\n\n### 7. 测试 API - MCP 服务器管理\n- 将 `openapi\u002Fmcp-gateway.openapi.json` 中的 OpenAPI 定义导入到 Postman、Bruno 或 Swagger Editor 等工具中。\n\n- 发送请求以创建新的适配器资源：\n  ```http\n  POST http:\u002F\u002Flocalhost:8000\u002Fadapters\n  Content-Type: application\u002Fjson\n  ```\n   ```json\n   {\n      \"name\": \"mcp-example\",\n      \"imageName\": \"mcp-example\",\n      \"imageVersion\": \"1.0.0\",\n      \"description\": \"test\"\n   }\n   ```\n\n### 8. 测试 API - MCP 服务器访问 \n- 部署 MCP 服务器后，使用 VS Code 等客户端测试连接。参考指南：[在 VS Code 中使用 MCP 服务器](https:\u002F\u002Fcode.visualstudio.com\u002Fdocs\u002Fcopilot\u002Fchat\u002Fmcp-servers)。\n  > **注意**：请确保 VSCode 是最新版本，以便使用最新的 MCP 功能。\n\n  - 要连接到已部署的 `mcp-example` 服务器，使用：\n     - `http:\u002F\u002Flocalhost:8000\u002Fadapters\u002Fmcp-example\u002Fmcp`（流式 HTTP）\n\n  示例 `.vscode\u002Fmcp.json` 文件，用于连接到 `mcp-example` 服务器：\n  ```json\n  {\n    \"servers\": {\n      \"mcp-example\": {\n        \"url\": \"http:\u002F\u002Flocalhost:8000\u002Fadapters\u002Fmcp-example\u002Fmcp\",\n      }\n    }\n  }\n  ```\n\n- 对于其他服务器：\n  - `http:\u002F\u002Flocalhost:8000\u002Fadapters\u002F{name}\u002Fmcp`（流式 HTTP）\n\n### 9. 测试工具注册与动态路由\n\n#### 构建并发布工具服务器镜像\n\n首先，构建并推送工具服务器镜像到本地注册表：\n```sh\ndocker build -f sample-servers\u002Ftool-example\u002FDockerfile sample-servers\u002Ftool-example -t localhost:5000\u002Fweather-tool:1.0.0\ndocker push localhost:5000\u002Fweather-tool:1.0.0\n```\n\n#### 注册工具\n\n发送请求以注册工具及其定义：\n```http\nPOST http:\u002F\u002Flocalhost:8000\u002Ftools\nContent-Type: application\u002Fjson\n```\n```json\n{\n  \"name\": \"weather\",\n  \"imageName\": \"weather-tool\",\n  \"imageVersion\": \"1.0.0\",\n  \"description\": \"天气工具，用于获取当前天气信息\",\n  \"toolDefinition\": {\n    \"tool\": {\n      \"name\": \"weather\",\n      \"title\": \"天气信息\",\n      \"description\": \"获取指定地点的当前天气。\",\n      \"type\": \"http\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"location\": {\n            \"type\": \"string\",\n            \"description\": \"城市和州，例如旧金山, CA\"\n          }\n        },\n        \"required\": [\"location\"]\n      }\n    },\n    \"port\": 8000\n  }\n}\n```\n\n#### 验证工具部署\n\n检查工具部署状态：\n```http\nGET http:\u002F\u002Flocalhost:8000\u002Ftools\u002Fweather\u002Fstatus\n```\n\n#### 通过工具网关路由器测试工具路由\n\n使用 MCP 客户端（如 VS Code）连接到工具网关路由器：\n\n示例 `.vscode\u002Fmcp.json` 文件，用于连接到工具网关路由器：\n```json\n{\n  \"servers\": {\n    \"tool-gateway\": {\n      \"url\": \"http:\u002F\u002Flocalhost:8000\u002Fmcp\"\n    }\n  }\n}\n```\n\n路由器会根据 MCP 请求中的工具名称，自动将工具调用路由到相应的已注册工具服务器。\n\n### 10. 清理环境  \n   要移除所有已部署的资源，删除 Kubernetes 命名空间：\n   ```sh\n   kubectl delete namespace adapter\n   ```\n\n## 快速入门 - 部署到 Azure\n\n### 云基础设施\n![架构图](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmicrosoft_mcp-gateway_readme_5191cfb08cff.png)\n\n### 1. 准备云开发环境\n- 拥有 **所有者** 权限的活跃 [Azure 订阅](https:\u002F\u002Fazure.microsoft.com)\n- [安装 Azure CLI](https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fcli\u002Fazure\u002Finstall-azure-cli)\n\n### 2. 设置 Entra ID（Azure Active Directory）\n\n云端部署的服务需要使用 Azure Entra ID 进行承载令牌身份验证。请按照以下步骤配置应用程序注册。\n\n#### 创建并配置应用程序注册\n\n1. 前往 [应用注册](https:\u002F\u002Fportal.azure.com\u002F#view\u002FMicrosoft_AAD_RegisteredApps\u002FApplicationsListBlade)\n2. 单击 **+ 新建注册**\n   - **名称**：选择一个有意义的名称，例如 `mcp-gateway`\n   - **支持的帐户类型**：选择 **单一租户**\n   - 单击 **注册**\n\n3. 转到应用程序注册的 **概述** 页面，复制：\n   - **应用程序（客户端）ID** — 这是您用于部署的 API 客户端 ID\n\n#### 公开 API（定义范围）\n\n1. 在左侧菜单中，转到 **公开 API**\n2. 单击 **应用程序 ID URI** 旁边的 **添加**，并将其保留为默认值：\n   ```\n   api:\u002F\u002F\u003Cyour-client-id>\n   ```\n\n3. 单击 **+ 添加范围**\n   - **范围名称**：`access`\n   - **管理员同意显示名称**：`Access MCP Gateway`\n   - **管理员同意描述**：任意简短描述\n   - 单击 **添加范围**\n\n#### 授权 Azure CLI 和 VS Code 作为客户端应用程序\n\n以允许 Azure CLI 和 VS Code 作为获取令牌的客户端。\n\n1. 仍在 **公开 API** 中，向下滚动至 **已授权的客户端应用程序**\n2. 单击 **+ 添加客户端应用程序**\n   - **客户端 ID**：`04b07795-8ddb-461a-bbee-02f9e1bf7b46`（Azure CLI）\n   - **客户端 ID**：`aebc6443-996d-45c2-90f0-388ff96faa56`（VS Code）\n   - 在已授权范围中，选择范围 `access`\n   - 单击 **添加**\n\n#### 配置应用程序角色以进行授权\n[docs\u002Fentra-app-roles.md](docs\u002Fentra-app-roles.md)\n\n### 3. 部署服务资源\n\n[![部署到 Azure](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmicrosoft_mcp-gateway_readme_7343390a6970.png)](https:\u002F\u002Fportal.azure.com\u002F#create\u002FMicrosoft.Template\u002Furi\u002Fhttps%3A%2F%2Fraw.githubusercontent.com%2Fmicrosoft%2Fmcp-gateway%2Fmain%2Fdeployment%2Finfra%2Fazure-deployment.json)\n\n**参数**\n| 名称              | 描述                                                                                                      |\n|-------------------|------------------------------------------------------------------------------------------------------------------|\n| `resourceGroup`   | 资源组的名称。必须仅包含小写字母和数字（字母数字）。                 |\n| `clientId`        | 您的应用程序注册中的 Entra ID（Azure AD）客户端 ID。                                                    |\n| `location`        | *(可选)* 将部署资源的 Azure 区域。\u003Cbr\u002F>默认为资源组所在的位置。   |\n| `resourceLabel`   | *(可选)* 用于命名资源后缀以及 DNS 标签的小写字母数字字符串。\u003Cbr\u002F>如果未提供，则将使用资源组名称。\u003Cbr\u002F>**建议：** 将此值设置为与资源组名称相同的默认值，并确保资源组名称仅包含小写字母数字字符。 |\n\n\n部署将：\n- 通过 Bicep 模板部署 Azure 基础设施\n\n   | 资源名称                 | 资源类型               |\n   |-------------------------------|-----------------------------|\n   | mgreg\\\u003CresourceLabel>         | 容器注册表          |\n   | mg-storage-\\\u003CresourceLabel>   | Azure Cosmos DB 账户     |\n   | mg-aag-\\\u003CresourceLabel>       | 应用程序网关         |\n   | mg-ai-\\\u003CresourceLabel>        | 应用程序洞察         |\n   | mg-aks-\\\u003CresourceLabel>       | Kubernetes 服务 (AKS)    |\n   | mg-identity-\\\u003CresourceLabel>  | 托管标识             |\n   | mg-pip-\\\u003CresourceLabel>       | 公共 IP 地址           |\n   | mg-vnet-\\\u003CresourceLabel>      | 虚拟网络             |\n\n- 将 Kubernetes 资源（包括 `mcp-gateway`）部署到已 provisioned 的 AKS 集群\n\n> **注意：** 建议使用托管标识进行无凭据身份验证。本次部署遵循该设计。\n\n### 4. 构建并发布 MCP 服务器镜像\n网关服务在部署期间会从新 provisioned 的 Azure 容器注册表 (ACR) 中拉取 MCP 服务器镜像。\n\n在 ACR 中构建 MCP 服务器镜像：\n\n```sh\naz acr build -r \"mgreg$resourceLabel\" -f sample-servers\u002Fmcp-example\u002FDockerfile sample-servers\u002Fmcp-example -t \"mgreg$resourceLabel.azurecr.io\u002Fmcp-example:1.0.0\"\n```\n\n### 5. 测试 API - MCP 服务器管理\n\n- 将 OpenAPI 规范从 `openapi\u002Fmcp-gateway.openapi.json` 导入到 [Postman](https:\u002F\u002Fwww.postman.com\u002F)、[Bruno](https:\u002F\u002Fwww.usebruno.com\u002F) 或 [Swagger Editor](https:\u002F\u002Feditor.swagger.io\u002F) 中\n\n- 在本地获取承载令牌：\n  ```sh\n  az account get-access-token --resource $clientId\n  ```\n\n- 发送 POST 请求以创建适配器资源：\n  ```http\n  POST http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Fadapters\n  Authorization: Bearer \u003Ctoken>\n  Content-Type: application\u002Fjson\n  ```\n  ```json\n  {\n    \"name\": \"mcp-example\",\n    \"imageName\": \"mcp-example\",\n    \"imageVersion\": \"1.0.0\",\n    \"description\": \"test\",\n    \"requiredRoles\": [] \u002F\u002F 添加 entra id 应用程序角色以限制访问\n  }\n  ```\n\n### 6. 测试 API - MCP 服务器访问\n\n- 部署 MCP 服务器后，可以使用像 [VS Code](https:\u002F\u002Fcode.visualstudio.com\u002F) 这样的客户端来测试连接。请参考指南：[在 VS Code 中使用 MCP 服务器](https:\u002F\u002Fcode.visualstudio.com\u002Fdocs\u002Fcopilot\u002Fchat\u002Fmcp-servers)。\n  > **注意：** 确保 VSCode 是最新版本，以便访问最新的 MCP 功能。\n\n  - 要连接到已部署的 `mcp-example` 服务器，请使用：\n     - `http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Fadapters\u002Fmcp-example\u002Fmcp`（可流式传输的 HTTP）\n\n  示例 `.vscode\u002Fmcp.json` 文件，用于连接到 `mcp-example` 服务器\n  ```json\n  {\n    \"servers\": {\n      \"mcp-example\": {\n        \"url\": \"http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Fadapters\u002Fmcp-example\u002Fmcp\",\n      }\n    }\n  }\n  ```\n  > **注意：** 访问 MCP 服务器仍需身份验证，VS Code 将帮助处理身份验证过程。\n\n- 对于其他服务器：\n  - `http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Fadapters\u002F{name}\u002Fmcp`（可流式传输的 HTTP）\n\n### 7. 测试工具注册与动态路由\n\n#### 构建并发布工具服务器镜像\n\n构建并将工具服务器镜像推送到 ACR：\n```sh\naz acr build -r \"mgreg$resourceLabel\" -f sample-servers\u002Ftool-example\u002FDockerfile sample-servers\u002Ftool-example -t \"mgreg$resourceLabel.azurecr.io\u002Fweather-tool:1.0.0\"\n```\n\n#### 注册工具\n\n获取承载令牌：\n```sh\naz account get-access-token --resource $clientId\n```\n\n发送请求以使用其定义注册工具：\n```http\nPOST http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Ftools\nAuthorization: Bearer \u003Ctoken>\nContent-Type: application\u002Fjson\n```\n```json\n{\n  \"name\": \"weather\",\n  \"imageName\": \"weather-tool\",\n  \"imageVersion\": \"1.0.0\",\n  \"useWorkloadIdentity\": true,\n  \"description\": \"用于获取当前天气信息的天气工具\",\n  \"requiredRoles\": [], \u002F\u002F 添加 Entra ID 应用程序角色以限制访问\n  \"toolDefinition\": {\n    \"tool\": {\n      \"name\": \"weather\",\n      \"title\": \"天气信息\",\n      \"description\": \"获取指定位置的当前天气。\",\n      \"type\": \"http\",\n      \"inputSchema\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"location\": {\n            \"type\": \"string\",\n            \"description\": \"城市和州，例如旧金山，加州\"\n          }\n        },\n        \"required\": [\"location\"]\n      },\n      \"annotations\": {\n        \"readOnly\": true\n      }\n    },\n    \"port\": 8000\n  }\n}\n```\n\n#### 验证工具部署\n\n检查工具部署状态：\n```http\nGET http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Ftools\u002Fweather\u002Fstatus\nAuthorization: Bearer \u003Ctoken>\n```\n\n#### 通过工具网关路由器测试工具路由\n\n使用 MCP 客户端（如 VS Code）连接到工具网关路由器：\n\n示例 `.vscode\u002Fmcp.json` 文件，用于连接到工具网关路由器：\n```json\n{\n  \"servers\": {\n    \"tool-gateway\": {\n      \"url\": \"http:\u002F\u002F\u003CresourceLabel>.\u003Clocation>.cloudapp.azure.com\u002Fmcp\"\n    }\n  }\n}\n```\n> **注意：** 需要进行身份验证。VS Code 将自动处理身份验证过程。\n\n路由器会根据 MCP 请求中的工具名称，自动将工具调用路由到相应的已注册工具服务器。\n\n### 8. 清理环境\n要删除所有已部署的资源，请在 Azure 门户中删除资源组，或运行以下命令：\n```sh\naz group delete --name \u003CresourceGroupName> --yes\n```\n\n### 9. 生产环境上线\n\n- **TLS 配置**  \n  使用有效的 TLS 证书在 Azure 应用程序网关 (AAG) 监听器上设置 HTTPS。\n\n- **网络安全**  \n  限制虚拟网络内的入站流量，并配置专用终结点以增强网络安全。\n\n- **遥测**  \n  启用高级遥测、详细指标和警报，以支持生产环境中的监控和故障排除。\n\n- **扩展性**  \n  根据预期负载调整 `mcp-gateway` 服务和 MCP 服务器的扩展策略。\n\n- **身份验证与授权**  \n  设置使用 Azure Entra ID (AAD) 的 OAuth 2.0 身份验证。\n  实施基于 RBAC 或自定义 ACL 的细粒度访问控制，以实现 `adapter` 级别的权限管理。\n\n## 贡献\n本项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议 (CLA)，声明您有权且确实授予我们使用您贡献的权利。有关详情，请访问 https:\u002F\u002Fcla.opensource.microsoft.com。\n\n当您提交拉取请求时，CLA 机器人会自动确定您是否需要提供 CLA，并相应地标记 PR（例如状态检查、评论）。只需按照机器人提供的指示操作即可。对于使用我们 CLA 的所有仓库，您只需执行此操作一次。\n\n本项目已采用 [微软开源行为准则](https:\u002F\u002Fopensource.microsoft.com\u002Fcodeofconduct\u002F)。有关更多信息，请参阅 [行为准则常见问题解答](https:\u002F\u002Fopensource.microsoft.com\u002Fcodeofconduct\u002Ffaq\u002F)，或如有任何其他疑问或意见，请联系 [opencode@microsoft.com](mailto:opencode@microsoft.com)。\n\n## 商标\n本项目可能包含项目、产品或服务的商标或徽标。未经授权使用微软商标或徽标须遵守并遵循 [微软商标与品牌指南](https:\u002F\u002Fwww.microsoft.com\u002Fen-us\u002Flegal\u002Fintellectualproperty\u002Ftrademarks\u002Fusage\u002Fgeneral)。在本项目的修改版本中使用微软商标或徽标不得造成混淆或暗示微软的赞助。任何第三方商标或徽标的使用均受该第三方政策的约束。\n\n## 数据收集\n本软件可能会收集有关您及您使用本软件的信息，并将其发送给微软。微软可能会利用这些信息来提供服务并改进我们的产品和服务。您可以按照仓库中的说明关闭遥测功能。此外，本软件中的一些功能也可能使您和微软能够从您的应用程序用户处收集数据。如果您使用这些功能，则必须遵守适用法律，包括向您的应用程序用户提供适当的通知以及微软隐私声明的副本。我们的隐私声明位于 https:\u002F\u002Fgo.microsoft.com\u002Ffwlink\u002F?LinkID=824704。您可以在帮助文档和我们的隐私声明中了解更多关于数据收集和使用的相关信息。您使用本软件即表示您同意这些做法。","# MCP Gateway 快速上手指南\n\nMCP Gateway 是一个专为 Kubernetes 环境设计的反向代理和管理层，用于托管、路由和管理模型上下文协议（MCP）服务器。它支持会话感知路由、动态工具分发以及企业级的权限控制。\n\n## 1. 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **操作系统**: Windows, macOS 或 Linux\n*   **.NET SDK**: 版本 8.0 或更高 ([下载链接](https:\u002F\u002Fdotnet.microsoft.com\u002Fen-us\u002Fdownload\u002Fdotnet\u002F8.0))\n*   **Docker Desktop**: 已安装并运行 ([下载链接](https:\u002F\u002Fdocs.docker.com\u002Fdesktop\u002F))\n*   **Kubernetes**: 已在 Docker Desktop 中启用，或拥有可访问的 K8s 集群\n    *   *国内用户提示*: 如果拉取镜像困难，建议配置 Docker 镜像加速器（如阿里云、腾讯云等）或在 `daemon.json` 中配置国内源。\n*   **kubectl**: 已安装并配置好与本地集群的连接\n*   **API 测试工具**: 推荐安装 [Postman](https:\u002F\u002Fwww.postman.com\u002F)、[Bruno](https:\u002F\u002Fwww.usebruno.com\u002F) 或 VS Code 插件用于测试 MCP 连接\n\n## 2. 安装与部署步骤\n\n以下流程基于本地 Docker + Kubernetes 环境进行快速部署。\n\n### 第一步：启动本地 Docker 注册表\n运行一个本地的 Docker Registry 用于存储构建的镜像：\n```sh\ndocker run -d -p 5000:5000 --name registry registry:2.7\n```\n\n### 第二步：构建并发布示例 MCP 服务器镜像\n构建一个示例 MCP 服务并推送到本地注册表：\n```sh\ndocker build -f sample-servers\u002Fmcp-example\u002FDockerfile sample-servers\u002Fmcp-example -t localhost:5000\u002Fmcp-example:1.0.0\ndocker push localhost:5000\u002Fmcp-example:1.0.0\n```\n\n### 第三步：构建并发布 MCP Gateway 及工具路由镜像\n使用 .NET CLI 发布网关服务（需确保项目路径正确）：\n\n发布 MCP Gateway:\n```sh\ndotnet publish dotnet\u002FMicrosoft.McpGateway.Service\u002Fsrc\u002FMicrosoft.McpGateway.Service.csproj -c Release \u002Fp:PublishProfile=localhost_5000.pubxml\n```\n\n发布 Tool Gateway Router (可选，如需使用动态工具路由):\n```sh\ndotnet publish dotnet\u002FMicrosoft.McpGateway.Tools\u002Fsrc\u002FMicrosoft.McpGateway.Tools.csproj -c Release \u002Fp:PublishProfile=localhost_5000.pubxml\n```\n\n### 第四步：部署到 Kubernetes\n应用部署配置文件将网关启动在集群中：\n```sh\nkubectl apply -f deployment\u002Fk8s\u002Flocal-deployment.yml\n```\n\n### 第五步：端口转发\n将网关服务端口映射到本地，以便外部访问：\n```sh\nkubectl port-forward -n adapter svc\u002Fmcpgateway-service 8000:8000\n```\n\n## 3. 基本使用\n\n部署完成后，您可以通过 REST API 管理 MCP 服务器，并通过标准 MCP 客户端进行连接。\n\n### 3.1 注册一个新的 MCP 服务器 (Adapter)\n使用 API 工具（如 Postman 或 curl）发送请求来部署并注册一个 MCP 服务：\n\n**请求:**\n```http\nPOST http:\u002F\u002Flocalhost:8000\u002Fadapters\nContent-Type: application\u002Fjson\n```\n\n**Body:**\n```json\n{\n   \"name\": \"mcp-example\",\n   \"imageName\": \"mcp-example\",\n   \"imageVersion\": \"1.0.0\",\n   \"description\": \"test\"\n}\n```\n\n### 3.2 连接 MCP 服务器\n注册成功后，您可以使用支持 MCP 的客户端（如最新版的 VS Code）进行连接。\n\n**VS Code 配置示例 (` .vscode\u002Fmcp.json`):**\n```json\n{\n  \"servers\": {\n    \"mcp-example\": {\n      \"url\": \"http:\u002F\u002Flocalhost:8000\u002Fadapters\u002Fmcp-example\u002Fmcp\"\n    }\n  }\n}\n```\n*注意：通用连接地址格式为 `http:\u002F\u002Flocalhost:8000\u002Fadapters\u002F{name}\u002Fmcp`*\n\n### 3.3 (进阶) 注册工具并测试动态路由\n如果您需要管理具体的 MCP Tools 而非直接连接服务器，可以使用动态路由功能。\n\n1.  **构建工具镜像**:\n    ```sh\n    docker build -f sample-servers\u002Ftool-example\u002FDockerfile sample-servers\u002Ftool-example -t localhost:5000\u002Fweather-tool:1.0.0\n    docker push localhost:5000\u002Fweather-tool:1.0.0\n    ```\n\n2.  **注册工具定义**:\n    ```http\n    POST http:\u002F\u002Flocalhost:8000\u002Ftools\n    Content-Type: application\u002Fjson\n    ```\n    ```json\n    {\n      \"name\": \"weather\",\n      \"imageName\": \"weather-tool\",\n      \"imageVersion\": \"1.0.0\",\n      \"description\": \"Weather tool for getting current weather information\",\n      \"toolDefinition\": {\n        \"tool\": {\n          \"name\": \"weather\",\n          \"title\": \"Weather Information\",\n          \"description\": \"Gets the current weather for a specified location.\",\n          \"type\": \"http\",\n          \"inputSchema\": {\n            \"type\": \"object\",\n            \"properties\": {\n              \"location\": {\n                \"type\": \"string\",\n                \"description\": \"The city and state, e.g. San Francisco, CA\"\n              }\n            },\n            \"required\": [\"location\"]\n          }\n        }\n      }\n    }\n    ```\n\n3.  **通过统一入口调用**:\n    客户端只需连接统一端点 `http:\u002F\u002Flocalhost:8000\u002Fmcp`，网关会自动根据工具定义将请求路由到对应的 `weather` 服务实例。","某金融科技公司正在构建基于 Kubernetes 的企业级 AI 助手平台，需动态调度数十个处理敏感数据的 MCP 服务器以支持多轮对话分析。\n\n### 没有 mcp-gateway 时\n- **会话状态断裂**：用户在进行多轮复杂查询时，请求被随机分发到不同 Pod，导致上下文记忆丢失，AI 无法连贯回答。\n- **运维管理混乱**：每次新增或更新一个数据分析工具，都需要手动修改 K8s 配置和路由规则，部署周期长达数小时且易出错。\n- **安全管控缺失**：缺乏统一的鉴权层，难以对内部不同团队访问特定 MCP 服务器实施细粒度的权限控制（RBAC）。\n- **扩展能力受限**：面对突发流量，无法自动实现基于会话的负载均衡，常因单点过载导致服务响应超时。\n\n### 使用 mcp-gateway 后\n- **会话精准保持**：利用 Session-Aware 路由机制，确保同一用户的所有请求始终指向同一个 MCP 实例，完美维持多轮对话上下文。\n- **生命周期自动化**：通过控制平面 API 即可一键完成工具的注册、扩容与升级，将新工具上线时间从小时级缩短至分钟级。\n- **统一安全网关**：内置数据面与控制面双重鉴权，轻松集成企业现有身份系统，实现对每个工具调用的精细化访问控制。\n- **弹性高可用**：自动感知后端 Pod 状态并智能分流，在流量高峰期间无缝横向扩展，保障核心业务零中断。\n\nmcp-gateway 通过将复杂的分布式会话管理与运维逻辑标准化，让企业能够像管理微服务一样高效、安全地规模化运营 AI 工具生态。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmicrosoft_mcp-gateway_283ccc7c.png","microsoft","Microsoft","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fmicrosoft_4900709c.png","Open source projects and samples from Microsoft",null,"opensource@microsoft.com","OpenAtMicrosoft","https:\u002F\u002Fopensource.microsoft.com","https:\u002F\u002Fgithub.com\u002Fmicrosoft",[82,86,90,94,98],{"name":83,"color":84,"percentage":85},"C#","#178600",89,{"name":87,"color":88,"percentage":89},"Bicep","#519aba",5.8,{"name":91,"color":92,"percentage":93},"PowerShell","#012456",3.4,{"name":95,"color":96,"percentage":97},"Python","#3572A5",0.9,{"name":99,"color":100,"percentage":97},"Dockerfile","#384d54",572,60,"2026-04-10T10:07:17","MIT",5,"Linux, macOS, Windows","未说明",{"notes":109,"python":107,"dependencies":110},"该工具是基于 .NET 8 开发的 Kubernetes 原生应用，非 Python 项目。运行本地开发环境需安装 .NET 8 SDK、Docker Desktop 并启用 Kubernetes。部署依赖 Kubernetes 集群（支持 StatefulSets 和无头服务），可选择一键部署到 Azure 或在本地通过 kubectl 部署。认证支持 Azure Entra ID。",[111,112,113,114],".NET 8 SDK","Docker Desktop","Kubernetes","Azure Entra ID (可选)",[14,15,35,52,13],[117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133],"gateway","kubernetes","mcp","restful-api","asp-net-core","csharp","azure","ai","arm-deployments","bicep","powershell","api-gateway","cloud-computing","docker","cloud-computing-service","infrastructure-as-code","llm","2026-03-27T02:49:30.150509","2026-04-11T03:24:35.014205",[137,142,147,152,157,162],{"id":138,"question_zh":139,"answer_zh":140,"source_url":141},28745,"如何注册已经托管在 Lambda 或 Kubernetes 集群上的现有 MCP 服务？","可以通过引入新的 mcp-proxy 镜像来支持转发可流式传输的 HTTP 流量。该镜像允许将已托管的 MCP 服务（如通过 `\u002Fmcp` 路径访问）注册到网关中。具体配置和使用方法请参阅 [mcp-proxy-server README](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmcp-gateway\u002Fblob\u002Fmain\u002Fmcp-proxy-server\u002FREADME.md)。未来计划将此转发功能直接集成到网关层，以减少额外的跳转开销。","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmcp-gateway\u002Fissues\u002F24",{"id":143,"question_zh":144,"answer_zh":145,"source_url":146},28746,"遇到 OAuth 资源元数据验证错误（Protected Resource Metadata resource does not match）导致服务器初始化失败怎么办？","此错误通常是因为 `PublicOrigin` 配置未正确覆盖默认值（如 `http:\u002F\u002Flocalhost:8000\u002F`），导致与外部访问 URL 不匹配。解决方法如下：\n1. 更新 Kubernetes ConfigMap (`app-config`)，添加或修改 `PublicOrigin` 条目为实际的外部访问地址（例如：`PublicOrigin: https:\u002F\u002Fgateway.example.com\u002F`）。\n2. 如果使用了应用网关进行 HTTPS 终止，需在部署中设置环境变量 `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true`，以便 ASP.NET Core 应用能正确解析 X-Forwarded 头。\n3. 确保应用网关的后端设置中包含正确的主机名头转发。\n完成上述配置后重启服务即可解决。","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmcp-gateway\u002Fissues\u002F20",{"id":148,"question_zh":149,"answer_zh":150,"source_url":151},28747,"MCP Gateway 是否必须使用 Cosmos DB 作为存储后端？","不是必须的。虽然该项目默认使用 Cosmos DB 来同时满足存储和缓存需求以简化架构，但在生产环境中，您可以使用任何其他的存储和缓存提供商。建议的方案是使用关系型数据库进行数据存储，并搭配 Redis 或多层缓存策略来提升性能。","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmcp-gateway\u002Fissues\u002F44",{"id":153,"question_zh":154,"answer_zh":155,"source_url":156},28748,"可以在 Azure Container Apps (ACA) 环境中运行 MCP Gateway 吗？","不可以。MCP Gateway 的数据平面组件依赖 Kubernetes 的 kubectl 控制平面访问权限来获取部署信息以实现基于亲和性的路由；控制平面组件也需要 kubectl 权限来动态创建部署和启动 Pod。由于 Azure Container Apps 不提供对这些底层 Kubernetes 功能的直接访问权限，因此无法在该环境中运行 MCP Gateway。该方案需要完整的 Kubernetes 基础设施编排能力。","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmcp-gateway\u002Fissues\u002F21",{"id":158,"question_zh":159,"answer_zh":160,"source_url":161},28749,"VS Code MCP 扩展要求实现 OAuth 2.0 受保护资源元数据端点，如何在 MCP 服务器中配置以支持认证？","为了兼容 VS Code 的认证机制，MCP 服务器必须实现 OAuth 2.0 受保护资源元数据规范（RFC 9728）。具体需要：\n1. 提供 `\u002F.well-known\u002Foauth-protected-resource` 端点，返回包含 `resource`、`authorization_servers` 等信息的 JSON。\n2. 在 401 响应头中包含 `WWW-Authenticate`，并指定 `resource_metadata` 参数指向上述端点。\n该问题已在相关 PR (#18) 中得到解决，请确保使用更新了这些功能的最新版本的 gateway 镜像或参考最新文档进行配置。","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmcp-gateway\u002Fissues\u002F17",{"id":163,"question_zh":164,"answer_zh":165,"source_url":141},28750,"如何在向网关发起 HTTP 调用时添加自定义或标准头部信息？","在使用 mcp-proxy 镜像转发流量时，可以通过配置代理支持来处理头部信息。特别是在涉及 HTTPS 终止的场景下（如使用 Application Gateway），需要在 Kubernetes 部署中设置环境变量 `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true`，这样 ASP.NET Core 应用才能正确解释来自网关的 `X-Forwarded-*` 头部。此外，还需确保网关的后端设置中配置了正确的主机名头转发。详细配置可参考 [mcp-proxy-server README](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fmcp-gateway\u002Fblob\u002Fmain\u002Fmcp-proxy-server\u002FREADME.md)。",[]]