Skip to main content

HTTP 服务代理配置

以下是HTTP服务代理的具体配置示例,包含了路由、工具等配置:

配置说明

1. 基础配置

MCP Gateway 服务监听端口,默认 5235
进程ID文件路径,用于进程管理和重载
配置重载间隔时间,默认 600s
是否开启配置自动重载功能
可以把一份配置当作一个命名空间,建议按照服务或者领域来区分,某个服务里包含很多API接口,每个API接口对应一个Tool
  • name: 代理服务名称,全局唯一,用于标识不同的代理服务
  • tenant: 租户标识,用于多租户场景的数据隔离和权限管理

2. 路由配置

路由配置用于定义请求的转发规则:
目前默认情况下会在prefix的基础之上衍生出3个接入点:
  • SSE: ${prefix}/sse,如:/gateway/user/sse
  • SSE: ${prefix}/message,如:/gateway/user/message
  • StreamableHTTP: ${prefix}/mcp,如:/gateway/user/mcp

3. CORS配置

跨域资源共享(CORS)配置用于控制跨域请求的访问权限:
通常情况下,MCP Client是不需要开放跨域的

4. 服务配置

服务配置用于定义服务元信息、关联的工具列表,以及服务级别的配置
服务级别的配置,可以在tools中通过 {{.Config}} 引用。此处可以通过写死在配置文件里的方式,也可以通过从环境变量中获取的方式。通过环境变量注入的话,需要通过{{ env "ENV_VAR_NAME" }}的方式引用

5. 工具配置

工具配置用于定义具体的API调用规则,每个参数都可以设置默认值(default),当MCP请求中没有提供该参数时,将自动使用默认值。

5.1 请求参数组装

请求目标服务的时候会涉及组装参数的动作,目前有几个来源:
  1. .Config: 从服务级别的配置中提取值
  2. .Args: 直接从请求参数中提取值
  3. .Request: 从请求中提取的值,包括请求头.Request.Headers、请求体.Request.Body
参数位置(position)支持以下几种:
  • header: 参数将被放置在请求头中
  • query: 参数将被放置在URL查询字符串中
  • path: 参数将被放置在URL路径中
  • body: 参数将被放置在JSON格式的请求体中
  • form-data: 参数将被放置在multipart/form-data格式的请求体中,用于文件上传等场景
参数类型(type)支持以下几种:
  • string: 字符串类型
  • number: 数字类型
  • boolean: 布尔类型
  • array: 数组类型,需要配合 items 定义数组元素类型
  • object: 对象类型,可以使用 properties 定义对象结构
对于复杂的 array 类型参数,可以定义详细的元素结构:
当使用 form-data 作为参数位置时,不需要指定 requestBody,系统会自动将参数组装成 multipart/form-data 格式。 另外:headerquery 参数也会被自动注入到下游请求中(Header 的键名等于参数名,Query 以 URL 查询字符串形式追加)。例如:

Client(MCP 请求)

请求 arguments 示例(来自 MCP 客户端):

MCP Gateway

  • header 自动写入下游 Header(键名=参数名)
  • query 自动追加到 URL 查询字符串
  • form-data 自动组装 multipart/form-data
工具配置片段:

下游服务(HTTP 请求)

实际发送给下游的请求:
对于JSON格式的请求体,需要在 requestBody 中组装,比如:
包括 endpoint 即目标地址也可以使用以上的来源去提取值,比如 http://localhost:5236/users/{{.Args.email}}/preferences 就是从请求参数中提取的值

5.2 响应参数组装

响应体的组装和请求体的组装类似:
  1. .Response.Data: 从响应中提取的值,响应必须是JSON的格式才可以提取
  2. .Response.Body: 直接透传整个响应体,会忽略响应内容格式,直接传递给客户端
都是通过 .Response 来提取值,比如:

配置存储

网关代理配置可以通过以下两种方式存储:

数据库存储(推荐)

  • 支持 SQLite3、PostgreSQL、MySQL
  • 每个配置作为一条记录存储
  • 支持动态更新和热重载

文件存储

  • 每个配置单独存储为一个 YAML 文件
  • 类似 Nginx 的 vhost 配置方式
  • 文件名建议使用服务名称,如 mock-server.yaml

MCP 服务代理配置

除了代理 HTTP 服务外,MCP Gateway 还支持代理 MCP 服务,目前 stdio、SSE 和 streamable-http 三种传输协议都已支持

配置示例

以下是一个完整的 MCP 服务代理配置示例:

配置说明

1. MCP 服务类型

MCP Gateway 支持以下三种类型的 MCP 服务代理:
  • 通过标准输入输出与 MCP 服务进程通信
  • 适用于需要本地启动的 MCP 服务,如第三方 SDK
  • 配置参数包括 commandargsenv
  • 将 MCP 客户端的请求转发到支持 SSE 的上游服务
  • 适用于已有的支持 SSE 协议的 MCP 服务
  • 仅需配置 url 参数指向上游 SSE 服务地址
  • 将 MCP 客户端的请求转发到支持可流式 HTTP 的上游服务
  • 适用于已有的支持 MCP 协议的上游服务
  • 仅需配置 url 参数指向上游 MCP 服务地址

2. stdio 类型配置

stdio 类型的 MCP 服务配置示例:
通过 env 字段可以设置环境变量,支持从请求中提取值,例如 {{.Request.Headers.Apikey}} 表示从请求头中提取 Apikey 的值

3. SSE 类型配置

SSE 类型的 MCP 服务配置示例:

4. streamable-http 类型配置

streamable-http 类型的 MCP 服务配置示例:

5. 路由配置

对于 MCP 服务代理,路由配置与 HTTP 服务代理类似,CORS 则根据实际情况配置(通常生产环境一般是不会开启跨域的):
对于 MCP 服务,请求头和响应头中的 Mcp-Session-Id 是必须要支持的,否则客户端无法正常使用。

高级配置

通知器配置

通知器用于配置重载通知,支持多种方式:
通过系统信号进行通知,适用于单机部署
通过HTTP API进行通知,适用于远程管理
通过Redis发布订阅进行通知,适用于集群部署

环境变量注入

在配置中可以使用环境变量,支持默认值:

模板函数

在请求体和响应体模板中,可以使用模板函数来处理复杂数据:
将对象或数组转换为 JSON 字符串,用于处理复杂数据结构
对于简单的数组和对象,可以直接使用变量
使用 toJSON 函数可以确保复杂的对象和数组被正确序列化为 JSON 格式,特别适用于嵌套结构和包含特殊字符的数据。

复杂参数处理示例

以下是一个处理复杂参数的完整示例,展示了如何定义和使用 object 和 array 类型的参数:

文件上传处理

支持文件上传场景:

最佳实践

  • 使用环境变量存储敏感信息(如数据库密码、API密钥)
  • 在生产环境中限制CORS Origins,避免使用 ”*”
  • 启用OAuth2认证和适当的授权机制
  • 定期轮换API密钥和令牌
  • 使用加密的Redis连接存储会话数据
  • 合理设置超时时间和重载间隔
  • 使用Redis集群提高会话存储性能
  • 选择合适的日志级别,避免过多debug日志
  • 使用连接池减少连接开销
  • 对频繁调用的API进行缓存
  • 避免在模板中进行复杂计算
  • 使用有意义的工具和服务名称
  • 添加详细的描述信息
  • 保持配置文件的整洁和可读性
  • 配置日志轮转,避免磁盘空间不足
  • 监控PID文件和进程状态
  • 设置合适的通知器类型便于配置管理
  • 定期检查和更新配置
  • 在开发环境中充分测试配置
  • 使用mock服务进行集成测试
  • 验证所有参数和响应格式
  • 测试错误处理和边界情况

配置验证

在应用配置之前,建议进行以下验证:
1

语法检查

确保YAML语法正确,无缩进错误
2

环境变量验证

检查所有必需的环境变量是否已设置
3

存储连接测试

验证数据库或Redis连接配置是否正确
4

引用验证

检查所有引用关系是否正确,如server名称匹配
5

模板验证

验证Go Template语法和变量引用
6

端点测试

确保所有endpoint都可以正常访问
7

权限验证

确保PID文件路径有写入权限
更多关于Go Template的使用方法,请参考模板使用指南