使用说明

MCP网关演示

使用AgentGateway的模型上下文协议（MCP）网关的完整演示，具有基于路径的路由、公共和OAuth 2.1保护的路由、本地Duende IdentityServer和多个MCP后端（本地和远程）。

概述

此演示展示了：

代理网关 作为中央MCP网关(https://agentgateway.dev/)
基于路径的路由 在单个端点上有6条不同的MCP路由
公共路线 代理到远程MCP服务器（Context7、Kismet Travel、Microsoft Learn）
OpenAPI到MCP的转换 自动将Swagger Petstore REST API公开为MCP工具
受保护的路线 使用OAuth 2.1+DCR实现本地MCP后端（JSONPlaceholder、Weather）
工具复用 通过单个后端组合多个后端 /mixed 路线
本地Duende身份服务器 用于OAuth 2.1身份验证（使用测试用户alice/bob）
管理用户界面 用于网关监控和管理

建筑

+---------------------------------------------------------------+
|                     Desktop MCP Clients                        |
|              (OpenCode Desktop / MCP Inspector)                |
+---------------------------+-----------------------------------+
                            |
                            | MCP Protocol (Streamable HTTP)
                            v
+---------------------------------------------------------------+
|                   Nginx (localhost:8080)                       |
|                                                                |
|  gateway.localhost     -> AgentGateway (MCP routes)            |
|  gateway-ui.localhost  -> AgentGateway Admin UI                |
|  idp.localhost         -> IdentityServer                       |
|  inspector.localhost   -> MCP Inspector                        |
+---------------------------+-----------------------------------+
                            |
        +-------------------+-------------------+
        |                                       |
        v                                       v
+------------------+                  +-------------------+
| AgentGateway     |                  | IdentityServer    |
| (Port 3000)      |                  | (Port 5001)       |
| (Admin: 3001)    |                  +-------------------+
+--------+---------+
         |
         +------ Public (no auth) ------+------------------+
         |               |              |                  |
         v               v              v                  |
  +------------+  +------------+  +-------------+          |
  | Context7   |  | Kismet     |  | Microsoft   |          |
  | (remote)   |  | Travel     |  | Learn       |          |
  |            |  | (remote)   |  | (remote)    |          |
  +------------+  +------------+  +-------------+          |
         |                                                 |
         v                                                 |
  +-------------------+                                    |
  | Swagger Petstore  |                                    |
  | (OpenAPI -> MCP)  |                                    |
  | (remote)          |                                    |
  +-------------------+                                    |
         |                                                 |
         +------ Protected (OAuth+DCR) ---+                |
         |                |               |                |
         v                v               v
  +------------------+  +------------------+
  | JSONPlaceholder  |  | Weather MCP      |
  | MCP Server       |  | Server           |
  | (Port 8001)      |  | (Port 8002)      |
  +------------------+  +------------------+

快速开始

先决条件

Docker桌面或Docker引擎
Docker Compose

开始演示

# Using the start script
./scripts/start-demo.sh

# Or manually
docker compose up -d --build

访问演示

服务（通过端口8080上的nginx）

服务	URL
网关MCP	http://gateway.localhost:8080
网关管理UI	http://gateway-ui.localhost:8080
身份服务器	http://idp.localhost:8080
MCP检查员	http://inspector.localhost:8080
JSON占位符MCP	http://jsonplaceholder.localhost:8080
天气MCP	http://weather.localhost:8080

直接访问

服务	URL
网关MCP	http://localhost:3000
网关管理UI	http://localhost:3001
身份服务器	http://localhost:5001
MCP检查员	http://localhost:6274
JSON占位符MCP	http://localhost:8001
天气MCP	http://localhost:8002

网关路由

所有路线均通过以下网关提供服务 http://gateway.localhost:8080.

公共路由（无身份验证）

路由	路径	远程目标
背景7	`/context7/mcp`	https://mcp.context7.com/mcp
Kismet旅游	`/travel/mcp`	https://mcp.kismet.travel/mcp
微软学习	`/learn/mcp`	https://learn.microsoft.com/api/mcp
Swagger宠物店	`/petstore/mcp`	OpenAPI自动翻译https://petstore.swagger.io

受保护路由（OAuth 2.1+DCR）

这些路由需要通过本地IdentityServer进行身份验证。

路由	路径	后端
JSON占位符	`/placeholder/mcp`	jsonplaceholder mcp:8001
天气	`/weather/mcp`	天气预报：8002
混合	`/mixed/mcp`	JSON占位符+天气组合

这 /mixed route多路复用两个本地后端，通过单个端点公开来自两个服务器的所有工具。

配置

网关配置

网关通过以下方式配置 gateway/config.yaml 使用基于路径的路由：

config:
  adminAddr: "0.0.0.0:3001"

binds:
- port: 3000
  listeners:
  - routes:
    # Public - no auth, proxied to remote MCP servers or OpenAPI specs
    - name: context7
      matches:
      - path:
          pathPrefix: /context7
      backends:
      - mcp:
          targets:
          - name: context7
            mcp:
              host: https://mcp.context7.com/mcp

    # Public - OpenAPI to MCP auto-translation
    - name: petstore
      matches:
      - path:
          pathPrefix: /petstore
      backends:
      - mcp:
          targets:
          - name: petstore
            openapi:
              schema:
                file: /etc/agentgateway/petstore-openapi.json
              host: https://petstore.swagger.io

    # Protected - OAuth 2.1 with DCR
    - name: placeholder
      matches:
      - path:
          pathPrefix: /placeholder
      policies:
        mcpAuthentication:
          issuer: http://idp.localhost:8080
          audiences: [mcp-gateway]
          jwks:
            url: http://idp:5000/.well-known/openid-configuration/jwks
          resourceMetadata:
            resource: http://gateway.localhost:8080/placeholder
            authorization_servers:
            - http://idp.localhost:8080
          mode: strict
      backends:
      - mcp:
          targets:
          - name: jsonplaceholder
            mcp:
              host: http://jsonplaceholder-mcp:8001/sse

工具命名

AgentGateway会自动为工具添加后端名称前缀，以避免冲突：

jsonplaceholder_get_posts
jsonplaceholder_get_users
weather_get_current
weather_get_forecast

MCP检验员测试

打开MCP检查器http://inspector.localhost:8080
将服务器URL设置为网关路由：
- 公众： http://gateway.localhost:8080/context7/mcp
- 公共（OpenAPI）： http://gateway.localhost:8080/petstore/mcp
- 受保护的： http://gateway.localhost:8080/placeholder/mcp
选择传输：流式HTTP
连接并浏览可用工具

可用工具

JSONPlaceholder工具（8个工具）--通过 `/placeholder/mcp`

工具	说明	参数
`jsonplaceholder_get_posts`	列出所有博客文章	无
`jsonplaceholder_get_post`	通过ID获取特定帖子	`id` （整数）
`jsonplaceholder_get_comments`	获取帖子的评论	`post_id` （整数）
`jsonplaceholder_get_users`	列出所有用户	无
`jsonplaceholder_get_user`	按ID获取特定用户	`id` （整数）
`jsonplaceholder_get_todos`	列出所有待办事项	`user_id` （整数，可选）
`jsonplaceholder_get_albums`	列出所有相册	`user_id` （整数，可选）
`jsonplaceholder_get_photos`	从相册中获取照片	`album_id` （整数）

天气工具（3个工具）--通过 `/weather/mcp`

工具	说明	参数
`weather_get_current`	获取某个地点的当前天气	`location` （字符串，必填）， `units` （字符串，可选）
`weather_get_forecast`	获取某个地点的天气预报	`location` （字符串，必填）， `days` （整数，可选）， `units` （字符串，可选）
`weather_search_location`	搜索位置坐标	`query` （字符串，必填）

Swagger宠物店工具（自动生成）--通过 `/petstore/mcp`

这些工具是 自动生成 从宠物店API规范由AgentGateway的 OpenAPI到MCP 功能。不需要自定义MCP服务器代码。

工具	描述	HTTP方法
`petstore_addPet`	将新宠物添加到商店	POST/pet
`petstore_updatePet`	更新现有宠物	PUT/pet
`petstore_findPetsByStatus`	按状态查找宠物	GET/pet/findByStatus
`petstore_findPetsByTags`	按标签查找宠物	GET/pet/findByTags
`petstore_getPetById`	按ID查找宠物	GET/pet/{petId}
`petstore_updatePetWithForm`	用表单数据更新宠物	POST/pet/{petId}
`petstore_deletePet`	删除宠物	删除/pet/{petId}
`petstore_uploadFile`	上传宠物图片	POST/pet/{petId}/uploadImage
`petstore_getInventory`	按状态返回宠物库存	GET/商店/库存
`petstore_placeOrder`	订购宠物	邮寄/商店/订单
`petstore_getOrderById`	按ID查找采购订单	GET/store/order/{orderId}
`petstore_deleteOrder`	按ID删除采购订单	删除/存储/订单/{orderId}
`petstore_createUser`	创建用户	POST/user
`petstore_createUsersWithListInput`	创建用户列表	POST/user/createWithList
`petstore_loginUser`	用户登录系统	GET/user/login
`petstore_logoutUser`	注销当前用户	GET/user/logout
`petstore_getUserByName`	按用户名获取用户	Get/user/{username}
`petstore_updateUser`	更新用户	PUT/user/{username}
`petstore_deleteUser`	删除用户	删除/用户/｛用户名｝

混合（全部11种工具）-通过 `/mixed/mcp`

这 /mixed route公开了JSONPlaceholder和Weather后端的所有工具。

项目结构

mcp-gateway-demo/
+-- gateway/
|   +-- config.yaml              # AgentGateway configuration (routes, auth, backends)
+-- idp/                         # Local IdentityServer (OAuth/OIDC)
|   +-- IdentityServer/
|       +-- Program.cs           # Entry point
|       +-- Config.cs            # OAuth scopes and resources
|       +-- TestUsers.cs         # Test users (alice/bob)
|       +-- Dockerfile
+-- mcp-servers/
|   +-- jsonplaceholder/
|   |   +-- server.py            # JSONPlaceholder MCP server
|   |   +-- Dockerfile
|   +-- weather/
|       +-- server.py            # Weather MCP server
|       +-- Dockerfile
+-- nginx/
|   +-- nginx.conf               # Reverse proxy configuration
|   +-- snippets/                # CORS, headers, SSE support
+-- specs/
|   +-- SPECIFICATION.md         # Technical specification
+-- scripts/
|   +-- start-demo.sh            # Start script
+-- docker-compose.yml           # Service orchestration
+-- README.md                    # This file

Docker服务

代理网关

图像: ghcr.io/agentgateway/agentgateway:latest
端口：3000（MCP路由），3001（管理UI）
特性：基于路径的MCP路由、OAuth集成、远程MCP代理、管理UI
文档: https://agentgateway.dev/

身份服务器（IdP）

构建：本地Dockerfile(idp/IdentityServer)
端口: 5001
特性：OAuth 2.1/OpenID连接提供程序
测试用户：爱丽丝/爱丽丝，鲍勃/鲍勃
动态条件响应：动态客户注册 /connect/dcr

JSON占位符MCP

构建：本地Dockerfile
端口: 8001
运输：SSE（服务器发送事件）
外部API: https://jsonplaceholder.typicode.com/

天气MCP

构建：本地Dockerfile
端口: 8002
运输：SSE（服务器发送事件）
外部API: https://api.openweathermap.org/
API密钥：可选（使用不带键的模拟数据）

安全

OAuth 2.1流（受保护的路由）

用途 授权码+PKCE （对公共客户安全）
支持动态客户端注册（DCR）
来自本地IdentityServer的短期访问令牌
网关通过JWKS端点验证令牌
仅 /placeholder, /weather，以及 /mixed 路由需要身份验证

公共路线

/context7, /travel, /learn，以及 /petstore 路由没有身份验证
流量直接代理到远程MCP服务器或从OpenAPI规范转换而来

演示安全警告

重要：这是一个演示环境，有以下限制：

使用简单密码（alice/alice、bob/bob）测试用户
Local IdentityServer使用开发签名密钥
未经硬化不适合生产使用

文档

项目文件

规格 -详细技术规范

外部参考

代理网关 -网关文档
关闭 IdentityServer -OAuth/OIDC文档
JSON占位符 -虚假REST API指南
OpenWeatherMap API -天气API文件
Swagger宠物店 -宠物商店演示API
代理网关OpenAPI到MCP -OpenAPI后端文档
模型上下文协议 -MCP规范

故障排除

常见问题

网关未启动：检查 docker compose logs mcp-gateway
OAuth错误：验证IdP是否健康http://idp.localhost:8080/.well-已知/openid配置
工具不可见：确保MCP服务器正在运行(docker compose ps)
*.localhost 未解决：大多数浏览器/操作系统都能解析 *.localhost 到 127.0.0.1 默认情况下。如果没有，请将条目添加到hosts文件中。

调试命令

# Check all service status
docker compose ps

# View gateway logs
docker compose logs mcp-gateway

# View MCP server logs
docker compose logs jsonplaceholder-mcp
docker compose logs weather-mcp

# Test MCP servers directly
curl http://localhost:8001/sse
curl http://localhost:8002/sse

# Test gateway health
curl http://localhost:8080/health

许可证

此演示按原样提供，用于教育和演示目的。

单个组件：

代理网关：Apache 2.0
Duende IdentityServer：商用（此处使用演示服务器）
JSONPlaceholder：免费使用
OpenWeatherMap：提供免费层