{  
  "GmztaAPIKey": "",  
  "GmztaClientID": "",  
  "GmztaClientSecret": "",  
  "BaseURL": "https://api.gmzta.com",  
  "TokenURL": "https://nac.gmzta.com/connect/token",  
  "Port": 80,  
  "LogRetentionDays": 30  
}

字段说明：

GmztaAPIKey：API Key 认证凭证（下面两项与当前项二选一，均配置时当前配置项无效，均不配置时以MCP客户端为准）
GmztaClientID：OAuth 客户端 ID
GmztaClientSecret：OAuth 客户端密钥
BaseURL：飞网 API 服务地址
TokenURL：OAuth 获取令牌地址
Port：FW-MCP 服务端监听端口
LogRetentionDays：日志保留天数，小于 1 时回退默认值 30

运行目录示例：

Windows：

FW-MCP/  
|- FW-MCP-windows-amd64.exe  
|- config.json  
└─ logs/

Linux：

FW-MCP/  
|- FW-MCP-linux-amd64  
|- config.json  
└─ logs/

说明：

修改 config.json 后需要重启 FW-MCP 服务端

5.3 Docker Compose 部署

镜像地址：registry.cn-beijing.aliyuncs.com/gmzta/gmzta-mcp:latest

部署步骤：

创建部署目录，并准备 config.json 与 docker-compose.yml
按实际环境填写 config.json
编写并检查 docker-compose.yml
在部署目录执行 docker compose up -d

示例：

services:  
  fw-mcp:    
	  image: registry.cn-beijing.aliyuncs.com/gmzta/gmzta-mcp:latest    
	  container_name: fw-mcp    
	  restart: unless-stopped    
	  ports:      
		  - "80:80"    
	  volumes:      
		  - ./config.json:/app/gmzta-mcp-server/config.json      
		  - ./logs:/app/gmzta-mcp-server/logs

5.4 Windows 程序部署

下载地址：

https://pkgs.gmzta.com/binaryfile/mcp/FW-MCP-windows-amd64.exe

部署步骤：

下载程序
编辑 config.json
将程序与 config.json 放在同一目录
双击启动程序，或通过计划任务/服务方式托管启动

说明：

Windows 版本支持系统托盘运行
可通过托盘打开日志目录和配置文件

5.5 Linux 程序部署

下载地址：

https://pkgs.gmzta.com/binaryfile/mcp/FW-MCP-linux-amd64

部署步骤：

下载程序
编辑 config.json
将程序与 config.json 放在同一目录
执行以下命令赋予执行权限并启动

chmod +x ./FW-MCP-linux-amd64

./FW-MCP-linux-amd64

说明：

建议配合 systemd 或企业现有守护进程方案托管运行

6. 认证方式

6.1 模式一：服务端统一认证

适用于所有 MCP 客户端复用同一组飞网凭证的场景。

配置方式：

在 config.json 中填写 OAuth 或 API Key
MCP 客户端连接时无需再额外传认证头

生效规则：

当 config.json 同时具备 OAuth 和 API Key 时，优先使用 OAuth
当 config.json 未配置 OAuth、但配置了 API Key 时，使用 API Key
只要服务端已配置凭证，MCP 客户端请求头中的认证信息不会生效

6.2 模式二：客户端请求头认证

适用于多人共用同一 FW-MCP 服务端，但每个人使用自己的飞网凭证。

配置方式：

config.json 中不要配置 GmztaClientID、GmztaClientSecret、TokenURL 和 GmztaAPIKey
MCP 客户端使用 API Key 认证，请求头使用 X-API-Key
MCP 客户端使用 Token 认证，请求头使用 Authorization

X-API-Key 仅支持传递 API Key，Authorization 仅支持传递 Token（Bearer类型，Bearer前缀可省略），两者不能同时传入。

7. MCP 客户端接入

关键配置如下：

传输类型：streamableHttp
MCP 服务端地址：https://mcp.gmzta.com
请求头：X-API-Key=<你创建的KEY> 或 Authorization=<Token>

7.1 公共服务接入示例

公共 FW-MCP 服务端只能使用 API Key 认证（headers.X-API-Key 为必填），MCP 客户端配置示例如下（具体配置以实际工具要求为准）：

{  
  "name": "FW-MCP服务端",  
  "type": "streamableHttp",  
  "description": "FW-MCP服务端是飞网提供的 MCP（Model Context Protocol）服务程序，支持将飞网的节点、用户、DNS、访问策略、流量和团队设置能力接入到 MCP 客户端中。",  
  "baseUrl": "https://mcp.gmzta.com",  
  "headers": {  
    "X-API-Key": "gmzta-apikey-xxxxxxxx"  
  }  
}

7.2 私有化部署接入示例

公共服务场景下，仅能使用 X-API-Key
私有化部署场景下，如果服务端未配置统一凭证，MCP 客户端请求头可按需选择 X-API-Key 或 Authorization

8. 权限说明

公共 MCP 服务能调用哪些工具、能执行哪些操作，取决于 API Key 创建者的用户权限或 OAuth 对应的权限。

服务端统一配置 OAuth：所有用户共用服务端 OAuth 对应的权限
服务端统一配置 API Key：所有用户共用服务端 API Key 创建者对应的权限
用户请求头自行认证：每个用户使用自己请求头中的 API Key 创建者或 Token 对应的权限

这意味着：

OAuth 权限由创建 OAuth 客户端时勾选的权限范围决定
API Key 权限由 API Key 创建人的用户角色权限决定
能查询哪些数据、能否修改设备、用户、DNS、策略和团队设置，取决于当前认证身份是否具备对应权限

9. MCP 工具清单

9.1 节点类工具

工具名	说明
`gmzta_device_list`	获取当前网络中的所有设备节点
`gmzta_device_get`	获取指定节点详情
`gmzta_device_delete`	删除指定节点
`gmzta_device_approve`	批准或撤销节点的网络准入
`gmzta_device_name_set`	修改节点在网络中的名称
`gmzta_device_groups_set`	设置节点设备组
`gmzta_device_key_expire`	启用或禁用节点通信密钥过期，密钥过期后需要重新节点认证
`gmzta_device_routes_list`	查看指定节点开启的子网网关或出口网关的路由信息
`gmzta_device_routes_approve`	批准指定节点中的全部或者部分路由设置
`gmzta_device_routes_delete`	取消批准指定节点中的全部或者部分路由设置
`gmzta_device_traffic_summary`	按小时或者按天查询指定节点网络流量汇总
`gmzta_device_traffic_detail`
按小时查询指定节点的网络流量详情

9.2 用户类工具

工具名	说明
`gmzta_users_list_get`	获取团队网络全部用户列表
`gmzta_user_info_get`	获取指定用户详情
`gmzta_user_suspend_set`	暂停用户
`gmzta_user_restore_set`	恢复用户
`gmzta_user_delete`	删除用户
`gmzta_user_role_set`	修改用户角色

9.3 团队类工具

工具名	说明
`gmzta_team_traffic_logs`	获取团队指定节点间，指定时间段的流量日志明细
`gmzta_team_traffic_top20`	按天获取流量排名前 20 的节点
`gmzta_team_traffic_summary`	按天获取团队网络流量汇总
`gmzta_team_dns_nameservers_get`	获取团队网络 DNS 服务器配置
`gmzta_team_dns_nameservers_set`	设置团队网络 DNS 服务器配置
`gmzta_team_fwdns_get`	获取飞网节点域名解析功能开关
`gmzta_team_fwdns_set`	设置飞网节点域名解析功能开关
`gmzta_team_split_dns_get`	获取团队网络 split DNS 配置
`gmzta_team_split_dns_patch`	增加团队网络 split DNS 配置
`gmzta_team_split_dns_set`	修改团队网络 split DNS 配置
`gmzta_team_policy_get`	获取团队网络 ACL 访问策略
`gmzta_team_policy_patch`
增加团队网络 ACL 访问策略
`gmzta_team_policy_set`	设置团队网络 ACL 访问策略
`gmzta_team_services_get`	获取网络中提供的服务和系统清单
`gmzta_team_settings_get`	获取团队网络设置总览
`gmzta_team_settings_patch`	修改团队网络中的一条或多条设置
`gmzta_team_device_approval_set`	设置设备入网审批开关
`gmzta_team_user_approval_set`	设置用户审批开关
`gmzta_team_send_file_set`	设置文件发送开关
`gmzta_team_collection_service_set`	设置服务收集开关
`gmzta_team_self_net_set`	设置个人网络开关
`gmzta_team_auto_update_set`	设置自动更新开关
`gmzta_team_key_expiry_set`	设置密钥有效期天数
`gmzta_team_network_traffic_logs_set`	设置团队网络流量日志开关或者部分开关
`gmzta_team_allow_control_address_get`	获取控制面板管理角色访问地址白名单
`gmzta_team_allow_control_address_set`	全量设置控制面板管理角色访问地址白名单
`gmzta_team_allow_control_address_add`	增量添加控制面板管理角色访问地址白名单
`gmzta_team_allow_control_address_remove`	删除控制面板管理角色访问地址白名单

10. 常见问题

Q1：为什么MCP 客户端请求头认证没有生效？

因为 FW-MCP 服务端的 config.json 中已经配置了 OAuth 或 API Key，服务端凭证优先级高于请求头。

Q2：为什么调用工具时报认证失败？

常见原因：

BaseURL 或 TokenURL 配置错误
API Key / OAuth 凭证错误
凭证权限不足，导致认证校验失败
FW-MCP 服务端无法访问飞网 API

Q3：为什么修改 `config.json` 后没有生效？

因为配置只在进程启动时读取，修改后需要重启 FW-MCP 服务端。

Q4：Docker 部署为什么连不上？

重点检查：

容器端口是否正确映射
config.json 是否正确挂载到运行目录

Q5：为什么同时传 `Authorization` 和 `X-API-Key` 会失败？

因为当前实现明确要求：API Key 只能通过 X-API-Key 传递，Token 只能通过 Authorization 传递，两者不能同时传入。