HTTP 服务代理配置
以下是HTTP服务代理的具体配置示例,包含了路由、工具等配置:配置说明
1. 基础配置
port
port
MCP Gateway 服务监听端口,默认 5235
pid
pid
进程ID文件路径,用于进程管理和重载
reload_interval
reload_interval
配置重载间隔时间,默认 600s
reload_switch
reload_switch
是否开启配置自动重载功能
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)配置用于控制跨域请求的访问权限:4. 服务配置
服务配置用于定义服务元信息、关联的工具列表,以及服务级别的配置{{.Config}} 引用。此处可以通过写死在配置文件里的方式,也可以通过从环境变量中获取的方式。通过环境变量注入的话,需要通过{{ env "ENV_VAR_NAME" }}的方式引用
5. 工具配置
工具配置用于定义具体的API调用规则,每个参数都可以设置默认值(default),当MCP请求中没有提供该参数时,将自动使用默认值。5.1 请求参数组装
请求目标服务的时候会涉及组装参数的动作,目前有几个来源:.Config: 从服务级别的配置中提取值.Args: 直接从请求参数中提取值.Request: 从请求中提取的值,包括请求头.Request.Headers、请求体.Request.Body等
header: 参数将被放置在请求头中query: 参数将被放置在URL查询字符串中path: 参数将被放置在URL路径中body: 参数将被放置在JSON格式的请求体中form-data: 参数将被放置在multipart/form-data格式的请求体中,用于文件上传等场景
string: 字符串类型number: 数字类型boolean: 布尔类型array: 数组类型,需要配合items定义数组元素类型object: 对象类型,可以使用properties定义对象结构
array 类型参数,可以定义详细的元素结构:
form-data 作为参数位置时,不需要指定 requestBody,系统会自动将参数组装成 multipart/form-data 格式。
另外:header 和 query 参数也会被自动注入到下游请求中(Header 的键名等于参数名,Query 以 URL 查询字符串形式追加)。例如:
Client(MCP 请求)
请求 arguments 示例(来自 MCP 客户端):
MCP Gateway
header自动写入下游 Header(键名=参数名)query自动追加到 URL 查询字符串form-data自动组装 multipart/form-data
下游服务(HTTP 请求)
实际发送给下游的请求:
requestBody 中组装,比如:
endpoint 即目标地址也可以使用以上的来源去提取值,比如 http://localhost:5236/users/{{.Args.email}}/preferences 就是从请求参数中提取的值
5.2 响应参数组装
响应体的组装和请求体的组装类似:.Response.Data: 从响应中提取的值,响应必须是JSON的格式才可以提取.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 服务代理:stdio 类型
stdio 类型
- 通过标准输入输出与 MCP 服务进程通信
- 适用于需要本地启动的 MCP 服务,如第三方 SDK
- 配置参数包括
command、args和env
SSE 类型
SSE 类型
- 将 MCP 客户端的请求转发到支持 SSE 的上游服务
- 适用于已有的支持 SSE 协议的 MCP 服务
- 仅需配置
url参数指向上游 SSE 服务地址
streamable-http 类型
streamable-http 类型
- 将 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 则根据实际情况配置(通常生产环境一般是不会开启跨域的):高级配置
通知器配置
通知器用于配置重载通知,支持多种方式:Signal 通知
Signal 通知
通过系统信号进行通知,适用于单机部署
API 通知
API 通知
通过HTTP API进行通知,适用于远程管理
Redis 通知
Redis 通知
通过Redis发布订阅进行通知,适用于集群部署
环境变量注入
在配置中可以使用环境变量,支持默认值:模板函数
在请求体和响应体模板中,可以使用模板函数来处理复杂数据:toJSON
toJSON
将对象或数组转换为 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的使用方法,请参考模板使用指南。