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 保持一致，用于服务管理和热重载功能。

存储配置

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

disk 存储

配置会以文件的形式存放在磁盘里，每个配置单独一个文件，可以理解跟 nginx 的 vhost 一个道理

db 存储

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

配置示例

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

  # 数据库配置（当 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 模式

  # 磁盘配置（当 type 为 'disk' 时使用）
  disk:
    path: "${GATEWAY_STORAGE_DISK_PATH:}"               # 数据文件存储路径

通知配置

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

支持的通知方式

signal

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

api

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

redis

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

composite

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

通知角色说明

sender（发送者）

receiver（接收者）

both（双向）

配置示例

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。

配置文件位置

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

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

热重载机制

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

配置更新检测

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

配置验证

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

平滑切换

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

最佳实践

单机部署

集群部署

生产环境

快速开始

安装部署

配置说明

客户端使用

开发文档

API 文档

端点示例

​基础配置

​存储配置

disk 存储

db 存储

​配置示例

​通知配置

​支持的通知方式

signal

api

redis

composite

​通知角色说明

​配置示例

​会话存储配置

memory 存储

redis 存储

​配置示例

​Forward Headers 配置

​功能特性

头部过滤

客户端头部

参数头部

覆盖控制

​配置选项

​头部过滤逻辑

​使用示例

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

​示例 2: 阻止特定头部

​示例 3: 工具参数头部

​环境变量

​配置文件位置

​热重载机制

​最佳实践

基础配置

存储配置

配置示例

通知配置

支持的通知方式

通知角色说明

配置示例

会话存储配置

配置示例

Forward Headers 配置

功能特性

配置选项

头部过滤逻辑

使用示例

示例 1: 只允许特定头部

示例 2: 阻止特定头部

示例 3: 工具参数头部

环境变量

配置文件位置

热重载机制

最佳实践