MCP Gateway 配置 - Unla (MCP Gateway)

配置文件支持使用 ${VAR:default} 语法进行环境变量注入。如果环境变量未设置，将使用默认值。常见的做法是通过不同的 .env、.env.development、.env.prod 进行注入，当然也可以直接修改配置写死一个值。

基础配置

port: ${MCP_GATEWAY_PORT:5235}                      # 服务监听端口
pid: "${MCP_GATEWAY_PID:/var/run/mcp-gateway.pid}"  # PID文件路径

这里的 PID 和下面涉及的 PID 保持一致，用于服务管理和热重载功能。

存储配置

存储配置模块主要用于存储网关的代理配置信息。目前支持两种存储方式：

db 存储

存到数据库，每个配置是一条记录，支持 SQLite3、PostgreSQL、MySQL

api 存储

通过 API 端点存储配置，允许使用外部配置管理系统

配置示例

storage:
  type: "${GATEWAY_STORAGE_TYPE:db}"                    # 存储类型：db, api

  # 数据库配置（当 type 为 'db' 时使用）
  database:
    type: "${GATEWAY_DB_TYPE:sqlite}"                   # 数据库类型（sqlite,postgres, mysql）
    host: "${GATEWAY_DB_HOST:localhost}"                # 数据库主机地址
    port: ${GATEWAY_DB_PORT:5432}                       # 数据库端口
    user: "${GATEWAY_DB_USER:postgres}"                 # 数据库用户名
    password: "${GATEWAY_DB_PASSWORD:example}"          # 数据库密码
    dbname: "${GATEWAY_DB_NAME:./data/mcp-gateway.db}"  # 数据库名称或文件路径
    sslmode: "${GATEWAY_DB_SSL_MODE:disable}"           # 数据库连接的 SSL 模式

  # API 配置（当 type 为 'api' 时使用）
  api:
    url: "${GATEWAY_STORAGE_API_URL:}"                  # API 端点 URL
    configJSONPath: "${GATEWAY_STORAGE_API_CONFIG_JSON_PATH:}"  # API 响应中配置的 JSON 路径
    timeout: "${GATEWAY_STORAGE_API_TIMEOUT:30s}"       # 请求超时时间

通知配置

通知配置模块主要是用来当配置更新的时候如何让 mcp-gateway 感知到更新并进行热重载而无需重启服务。

支持的通知方式

signal

通过发送操作系统信号量来通知，类似 kill -SIGHUP <pid> 或者 nginx -s reload 这种方式

api

通过调用一个 API 的方式通知，mcp-gateway 会监听一个独立的端口

redis

通过 redis 的发布/订阅功能通知，适合单机或集群部署时使用

composite

组合通知，通过多种方式组合，默认 signal 和 api 一定会开启

通知角色说明

sender（发送者）

负责发送通知，apiserver 只能走这个模式

receiver（接收者）

负责接收通知，单机的 mcp-gateway 建议只走这个模式

both（双向）

既是发送者又是接收者，集群部署的 mcp-gateway 可以走这个方式

配置示例

notifier:
  role: "${NOTIFIER_ROLE:receiver}" # 角色：'sender'（发送者）或 'receiver'（接收者）
  type: "${NOTIFIER_TYPE:signal}"   # 类型：'signal'（信号）、'api'、'redis' 或 'composite'（组合）

  # 信号配置（当 type 为 'signal' 时使用）
  signal:
    signal: "${NOTIFIER_SIGNAL:SIGHUP}"                     # 要发送的信号
    pid: "${NOTIFIER_SIGNAL_PID:/var/run/mcp-gateway.pid}"  # PID 文件路径

  # API 配置（当 type 为 'api' 时使用）
  api:
    port: ${NOTIFIER_API_PORT:5235}                                         # API 端口
    target_url: "${NOTIFIER_API_TARGET_URL:http://localhost:5235/_reload}"  # 重载端点

  # Redis 配置（当 type 为 'redis' 时使用）
  redis:
    addr: "${NOTIFIER_REDIS_ADDR:localhost:6379}"                               # Redis 地址
    password: "${NOTIFIER_REDIS_PASSWORD:UseStrongPasswordIsAGoodPractice}"     # Redis 密码
    db: ${NOTIFIER_REDIS_DB:0}                                                  # Redis 数据库编号
    topic: "${NOTIFIER_REDIS_TOPIC:mcp-gateway:reload}"                         # Redis 发布/订阅主题

会话存储配置

会话存储配置用于存储 MCP 中的会话信息。根据不同的部署场景，可以选择不同的存储方式：

memory 存储

内存存储，适合单机部署（需注意，重启会失去会话信息）

redis 存储

Redis 存储，适合单机或集群部署，支持持久化

配置示例

session:
  type: "${SESSION_STORAGE_TYPE:memory}"                    # 存储类型：memory, redis
  redis:
    addr: "${SESSION_REDIS_ADDR:localhost:6379}"            # Redis 地址
    password: "${SESSION_REDIS_PASSWORD:}"                  # Redis 密码
    db: ${SESSION_REDIS_DB:0}                               # Redis 数据库编号
    topic: "${SESSION_REDIS_TOPIC:mcp-gateway:session}"     # Redis 发布/订阅主题

使用 memory 存储时，服务重启会导致所有会话信息丢失。生产环境建议使用 redis 存储。

Forward Headers 配置

Forward Headers 配置允许 MCP Gateway 将客户端请求中的 HTTP 头部转发到下游服务。此功能对于身份验证、请求追踪和自定义头部传播非常有用。

为了向后兼容，Forward Headers 功能默认为禁用状态。通过在配置中设置 enabled: true 来启用此功能。

功能特性

头部过滤

使用允许/忽略列表控制哪些头部被转发，支持大小写不敏感匹配

客户端头部

将客户端请求（tools/list 和 tools/call）中的头部转发到下游服务

参数头部

支持通过可配置的参数名称转发作为工具参数传递的头部

覆盖控制

选择是否覆盖现有头部或添加到现有头部

配置选项

forward:
  enabled: ${FORWARD_ENABLED:false}                                     # 启用 forward headers（默认：false）
  
  mcp_arg:
    key_for_header: "${FORWARD_MCP_ARG_KEY_FOR_HEADER:__forwardHeaders}" # 工具参数的参数名
  
  header:
    allow_headers: "${FORWARD_ALLOW_HEADERS:}"                          # 允许的头部列表，逗号分隔（优先级更高）
    ignore_headers: "${FORWARD_IGNORE_HEADERS:Accept, Accept-Encoding, Accept-Language, Host, Cookie, Connection, User-Agent, Content-Length, Content-Type}" # 要忽略的头部
    case_insensitive: ${FORWARD_HEADER_CASE_INSENSITIVE:true}           # 大小写不敏感的头部匹配
    override_existing: ${FORWARD_HEADER_OVERRIDE_EXISTING:false}        # 覆盖现有头部而不是添加

头部过滤逻辑

过滤逻辑遵循基于优先级的方法：

优先级检查

如果配置了 allow_headers（非空），它优先生效，ignore_headers 会被完全忽略

允许列表模式

当设置 allow_headers 时，只有此列表中的头部会被转发，其他所有头部都被忽略

忽略列表模式

当 allow_headers 为空时，ignore_headers 列表中的头部会被过滤掉，其他头部会被转发

大小写敏感性

头部匹配遵循 case_insensitive 设置，同时适用于允许和忽略列表

使用示例

示例 1: 只允许特定头部

forward:
  enabled: true
  header:
    allow_headers: "Authorization, X-API-Key, X-Request-ID"
    ignore_headers: "Host, Cookie"  # 这个会被忽略
    case_insensitive: true

结果: 只有 Authorization、X-API-Key 和 X-Request-ID 头部会被转发。

示例 2: 阻止特定头部

forward:
  enabled: true
  header:
    allow_headers: ""  # 空值 - 使用忽略列表
    ignore_headers: "Accept, Host, Cookie, User-Agent"
    case_insensitive: true

结果: 除了 Accept、Host、Cookie 和 User-Agent 外，所有头部都会被转发。

示例 3: 工具参数头部

forward:
  enabled: true
  mcp_arg:
    key_for_header: "custom_headers"
  header:
    override_existing: true

工具现在可以通过 custom_headers 参数传递头部：

{
  "name": "api_call",
  "arguments": {
    "url": "https://api.example.com/data",
    "custom_headers": {
      "Authorization": "Bearer token123",
      "X-Custom-Header": "value"
    }
  }
}

环境变量

所有 forward headers 设置都可以通过环境变量进行配置：

# 启用功能
FORWARD_ENABLED=true

# 配置头部转发行为
FORWARD_MCP_ARG_KEY_FOR_HEADER=__forwardHeaders
FORWARD_ALLOW_HEADERS="Authorization, X-API-Key"
FORWARD_IGNORE_HEADERS="Accept, Host, Cookie"
FORWARD_HEADER_CASE_INSENSITIVE=true
FORWARD_HEADER_OVERRIDE_EXISTING=false

在生产环境中启用 forward headers 时，请仔细审查应该转发哪些头部，以避免安全风险，如暴露敏感的身份验证令牌或 cookies。

链路追踪（OpenTelemetry → Jaeger）

MCP Gateway 支持通过 OpenTelemetry 将链路追踪数据导出到 Jaeger。该功能可选，默认关闭。

功能概览

入站 HTTP 请求通过 Gin 中间件自动打点（排除 /health_check）
下游 HTTP 调用自动透传 Trace 上下文
可选捕获下游请求的部分字段/Body 以及错误响应摘要，便于排障

配置示例

tracing:
  enabled: ${TRACING_ENABLED:false}
  service_name: "${TRACING_SERVICE_NAME:mcp-gateway}"
  endpoint: "${TRACING_ENDPOINT:localhost:4317}"   # Jaeger OTLP 采集端：gRPC(4317) 或 HTTP(4318)
  protocol: "${TRACING_PROTOCOL:grpc}"             # grpc 或 http
  insecure: ${TRACING_INSECURE:true}
  sampler_rate: ${TRACING_SAMPLER_RATE:0.1}         # 0.0 ~ 1.0
  environment: "${TRACING_ENV:dev}"
  headers: {}                                       # 可选导出器请求头
  capture:
    downstream_error:
      enabled: ${TRACING_ERR_BODY_ENABLED:false}
      max_body_length: ${TRACING_ERR_BODY_MAX_LEN:256}
    # 全局抓取设置 — 谨慎使用，避免泄露敏感信息。
    downstream_request:
      enabled: ${TRACING_REQ_ARGS_ENABLED:false}
      body_enabled: ${TRACING_REQ_BODY_ENABLED:false}
      body_max_length: ${TRACING_REQ_BODY_MAX_LEN:256}
      max_field_length: ${TRACING_REQ_ARG_MAX_LEN:256}
      include_fields: "${TRACING_INCLUDE_FIELDS:}"   # CSV 或 JSON Map: key=模板

环境变量

# 启用追踪与服务标识
TRACING_ENABLED=true
TRACING_SERVICE_NAME=mcp-gateway
TRACING_ENV=dev

# 导出器配置（二选一协议）
TRACING_PROTOCOL=grpc
TRACING_ENDPOINT=localhost:4317   # gRPC（OTLP）
# 或者：
# TRACING_PROTOCOL=http
# TRACING_ENDPOINT=http://localhost:4318  # HTTP（OTLP）
TRACING_INSECURE=true
TRACING_SAMPLER_RATE=1.0          # 开发建议 1.0；生产请适当降低

# 可选捕获项（生产慎用）
TRACING_ERR_BODY_ENABLED=true
TRACING_ERR_BODY_MAX_LEN=256
TRACING_REQ_ARGS_ENABLED=false
TRACING_INCLUDE_FIELDS="username={{.Args.username}},email={{.Args.email}}"
TRACING_REQ_ARG_MAX_LEN=256
TRACING_REQ_BODY_ENABLED=false
TRACING_REQ_BODY_MAX_LEN=256

本地启动 Jaeger

可使用项目内提供的 Compose 文件：deploy/docker/jaeger/docker-compose.yml
启动命令：docker compose -f deploy/docker/jaeger/docker-compose.yml up
Jaeger UI: http://localhost:16686

示例截图

开启字段或 Body 捕获可能会暴露敏感信息（令牌、密码、个人隐私）。建议默认关闭，在受控环境内以最小化采样与精确字段选择的方式使用。

配置文件位置

默认情况下，配置文件应放置在以下位置：

容器部署：/app/configs/mcp-gateway.yaml
二进制部署：./configs/mcp-gateway.yaml

热重载机制

MCP Gateway 支持热重载配置，无需重启服务即可应用新的配置：

配置更新检测

当配置发生变更时，通过配置的通知方式（signal、api、redis）触发重载

配置验证

重载前会验证新配置的合法性，确保服务稳定运行

平滑切换

验证通过后，平滑切换到新配置，不中断正在进行的连接

最佳实践

单机部署

存储类型建议使用 db 配合 SQLite
通知类型使用 composite 或 signal
会话存储可使用 memory 或 redis

集群部署

存储类型使用 db 配合 PostgreSQL 或 MySQL
通知类型使用 redis 或 composite
会话存储建议使用 redis

生产环境

使用强密码保护 Redis 和数据库
定期备份配置数据
监控服务健康状态和性能指标

​基础配置

​存储配置

db 存储

api 存储

​配置示例

​通知配置

​支持的通知方式

signal

api

redis

composite

​通知角色说明

​配置示例

​会话存储配置

memory 存储

redis 存储

​配置示例

​Forward Headers 配置

​功能特性

头部过滤

客户端头部

参数头部

覆盖控制

​配置选项

​头部过滤逻辑

​使用示例

​示例 1: 只允许特定头部

​示例 2: 阻止特定头部

​示例 3: 工具参数头部

​环境变量

​链路追踪（OpenTelemetry → Jaeger）

​功能概览

​配置示例

​环境变量

​本地启动 Jaeger

​示例截图

​配置文件位置

​热重载机制

​最佳实践

基础配置

存储配置

配置示例

通知配置

支持的通知方式

通知角色说明

配置示例

会话存储配置

配置示例

Forward Headers 配置

功能特性

配置选项

头部过滤逻辑

使用示例

示例 1: 只允许特定头部

示例 2: 阻止特定头部

示例 3: 工具参数头部

环境变量

链路追踪（OpenTelemetry → Jaeger）

功能概览

配置示例

环境变量

本地启动 Jaeger

示例截图

配置文件位置

热重载机制

最佳实践