中文英文
 编辑文档
 反馈问题
 社区讨论

本页导航

MCP 协议接入

# 介绍

Zadig MCP Server 将 Zadig 能力封装为 MCP 工具，可供 Cursor、Claude Code、Trae、VS Code、Codex、飞书 Aily 等 MCP 客户端调用。

Zadig MCP 提供 stdio、Streamable HTTP 两种主要接入方式，并提供旧 SSE 兼容端点，满足本地开发和远程共享服务两类场景。

# 使用说明

提示

  • Zadig 版本需为 v4.2.0 或以上。
  • 请在 Zadig 的账号设置中创建 API Token。
  • 请将文中的 https://your-zadig.com、https://mcp.your-company.com、your-token 替换为实际值。

MCP 可执行创建、更新、删除和运行工作流等操作。建议为每个用户或集成服务创建最小权限的 API Token；执行写操作前，请仔细确认目标项目、环境和参数。

远程请求中的 API Token 优先级如下：

  1. Authorization: Bearer <token> 请求头。
  2. URL 中的 api_token 参数。
  3. MCP Server 进程的 ZADIG_API_TOKEN 环境变量。

注意

URL 中的 Token 可能被保存在客户端配置中，或记录在反向代理、网关及服务端访问日志中。仅在客户端无法设置请求 Header 时使用 api_token，并确保 URL 不会泄露。

# 使用方式

方式适用场景
stdio本机安装，由 MCP 客户端启动 Zadig MCP Server。适用于 Cursor、Claude Code、Trae、VS Code、Codex 等客户端。
Streamable HTTP部署为远程服务，通过 /mcp 提供 MCP 能力。适用于集中部署和支持远程 MCP 的客户端。
SSE 兼容入口仅适用于尚不支持 Streamable HTTP 的旧客户端。服务端仍使用 HTTP 方式启动。

# stdio

stdio 方式无需部署独立服务，MCP 客户端在本机启动 Zadig MCP Server。

# 安装

Linux、macOS：

# 交互式安装：按提示输入 Zadig 地址和 Token，并选择需要配置的客户端
curl -fsSL https://resources.koderover.com/zadig-mcp/install.sh | sh
1
2

Windows PowerShell：

irm https://resources.koderover.com/zadig-mcp/install.ps1 | iex
1

交互式安装会下载对应平台的二进制，并自动配置 Cursor、Claude Code、Trae、VS Code、Codex 中选定的客户端。完成后请重启客户端。

也可使用非交互式安装。该方式不会自动写入客户端配置：

curl -fsSL https://resources.koderover.com/zadig-mcp/install.sh | \
  ZADIG_API_HOST=https://your-zadig.com \
  ZADIG_API_TOKEN=your-token \
  sh
1
2
3
4
$env:ZADIG_API_HOST="https://your-zadig.com"
$env:ZADIG_API_TOKEN="your-token"
irm https://resources.koderover.com/zadig-mcp/install.ps1 | iex
1
2
3

# 验证

重启 MCP 客户端后，在客户端的 MCP Servers 页面确认 zadig-mcp 状态正常；也可输入“检查 Zadig MCP 服务是否可用”，由客户端调用 zadig_ping 验证连接。

Zadig MCP Server 配置成功示例Zadig MCP Server 连接成功示例

若连接失败，请检查 Zadig 地址、API Token、二进制路径，以及配置中的 -a 127.0.0.1:3000 -t stdio 参数。

# 使用

安装脚本会自动写入配置。需要手动配置时，请在客户端的 MCP 配置中添加以下内容，并将 command 改为实际二进制路径。Linux 和 macOS 的默认安装路径为 ~/.local/bin/zadig-mcp。

{
  "mcpServers": {
    "zadig-mcp": {
      "command": "/path/to/zadig-mcp",
      "args": ["--a", "127.0.0.1:3000", "--t", "stdio"],
      "env": {
        "ZADIG_API_HOST": "https://your-zadig.com",
        "ZADIG_API_TOKEN": "your-token"
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12

-a 和 -t 均为必填参数。stdio 模式不使用网络监听地址，-a 可固定填写 127.0.0.1:3000。

Codex 使用 TOML 格式。默认配置文件为 ~/.codex/config.toml；若设置了 CODEX_HOME，则为 $CODEX_HOME/config.toml。

[mcp_servers.zadig-mcp]
command = "/path/to/zadig-mcp"
args = ["--a", "127.0.0.1:3000", "--t", "stdio"]

[mcp_servers.zadig-mcp.env]
ZADIG_API_HOST = "https://your-zadig.com"
ZADIG_API_TOKEN = "your-token"
1
2
3
4
5
6
7

配置完成后，可直接在客户端中使用自然语言操作 Zadig。例如：

查询 demo 项目下的工作流列表
检查 demo 项目的 dev 环境中 web 服务状态
为 release 工作流生成可执行参数模板
1
2
3

# 卸载

Linux、macOS：

# 升级到最新版本
curl -fsSL https://resources.koderover.com/zadig-mcp/install.sh | sh -s -- --update

# 检查是否有新版本
curl -fsSL https://resources.koderover.com/zadig-mcp/install.sh | sh -s -- --check

# 卸载
curl -fsSL https://resources.koderover.com/zadig-mcp/install.sh | sh -s -- --uninstall
1
2
3
4
5
6
7
8

Windows PowerShell：

# 卸载
& ([scriptblock]::Create((irm https://resources.koderover.com/zadig-mcp/install.ps1))) -Uninstall
1
2

# Streamable HTTP

Streamable HTTP 适用于集中部署 Zadig MCP Server。服务默认通过 /mcp 提供 MCP 接入，同时保留 /sse 和 /message 两个 SSE 兼容端点。

# 部署

可在 Zadig 中创建 K8s 项目和环境，将以下 YAML 作为服务配置加入环境。请根据实际环境修改 ZADIG_API_HOST、镜像地址和版本、MCP_ALLOWED_ORIGINS、Ingress Class、域名及命名空间。

apiVersion: v1
kind: ConfigMap
metadata:
  name: zadig-mcp-http-config
  labels:
    app: zadig-mcp-http
data:
  ZADIG_API_HOST: "https://your-zadig.com"
  MCP_TRANSPORT_TYPE: "http"
  MCP_LISTEN_ADDR: "0.0.0.0:3000"

  # Streamable HTTP 端点
  MCP_HTTP_ENDPOINT: "/mcp"

  # 旧 SSE 兼容端点
  MCP_SSE_ENDPOINT: "/sse"
  MCP_MESSAGE_ENDPOINT: "/message"

  # Web 应用调用时，填写该应用的 Origin；桌面 MCP 客户端通常可保持为空。
  MCP_ALLOWED_ORIGINS: ""

  # 审计默认关闭；确有需要时再启用。
  MCP_AUDIT_ENABLED: "false"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: zadig-mcp-http
  labels:
    app: zadig-mcp-http
spec:
  replicas: 1
  selector:
    matchLabels:
      app: zadig-mcp-http
  template:
    metadata:
      labels:
        app: zadig-mcp-http
    spec:
      containers:
        - name: zadig-mcp
          image: koderover.tencentcloudcr.com/koderover-public/zadig-mcp:0.2.0
          imagePullPolicy: IfNotPresent
          args:
            - "-t"
            - "$(MCP_TRANSPORT_TYPE)"
            - "-a"
            - "$(MCP_LISTEN_ADDR)"
          ports:
            - name: http
              containerPort: 3000
              protocol: TCP
          envFrom:
            - configMapRef:
                name: zadig-mcp-http-config
          resources:
            requests:
              cpu: 200m
              memory: 512Mi
            limits:
              cpu: 400m
              memory: 1024Mi
          readinessProbe:
            tcpSocket:
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            tcpSocket:
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 20
---
apiVersion: v1
kind: Service
metadata:
  name: zadig-mcp-http
  labels:
    app: zadig-mcp-http
spec:
  selector:
    app: zadig-mcp-http
  ports:
    - name: http
      port: 80
      targetPort: 3000
      protocol: TCP
  type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: zadig-mcp-http
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTP"
    nginx.ingress.kubernetes.io/service-upstream: "true"
    nginx.ingress.kubernetes.io/proxy-buffering: "off"
    nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-http-version: "1.1"
spec:
  ingressClassName: your-ingress-class
  rules:
    - host: mcp.your-company.com
      http:
        paths:
          - path: /mcp
            pathType: Prefix
            backend:
              service:
                name: zadig-mcp-http
                port:
                  number: 80
          - path: /sse
            pathType: Prefix
            backend:
              service:
                name: zadig-mcp-http
                port:
                  number: 80
          - path: /message
            pathType: Prefix
            backend:
              service:
                name: zadig-mcp-http
                port:
                  number: 80
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

示例中使用公开 demo 镜像 koderover.tencentcloudcr.com/koderover-public/zadig-mcp:0.2.0，可按需替换为其他实际可访问的 Zadig MCP Server 镜像。若需要为服务配置默认 Token，可将 ZADIG_API_TOKEN 以 Kubernetes Secret 注入 Deployment。远程客户端也可以各自通过请求头或 URL 参数传入 Token。

# 验证

  1. 在 Zadig 环境中确认 zadig-mcp-http Pod 已就绪，且服务日志中没有启动错误。
  2. 确认 Ingress 已生成并可访问 https://mcp.your-company.com/mcp。
  3. 按下方客户端配置接入后，调用 zadig_ping 验证 MCP 连接，并尝试查询一个有权限访问的项目。

# 使用

优先使用 /mcp，并通过请求 Header 传递 Token：

{
  "mcpServers": {
    "zadig-mcp": {
      "url": "https://mcp.your-company.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10

不支持自定义 Header 的客户端可以在 URL 中传递 Token：

https://mcp.your-company.com/mcp?api_token=your-token
1

飞书 Aily 支持 Streamable HTTP，推荐新增 MCP 服务时使用上述 /mcp 地址。若通过 URL 传递 Token，可直接填写：

https://mcp.your-company.com/mcp?api_token=your-token
1

保存后，可在 Aily 对话中调用 zadig_ping 或查询项目，验证连接和权限。

如需将 MCP 服务提供给浏览器侧的 Web 应用调用，应将该应用的完整 Origin 配置在 MCP_ALLOWED_ORIGINS 中。桌面 IDE 等 MCP 客户端通常不携带 Origin，无需该配置。多个 Origin 使用逗号分隔，不支持通配符。

# 参数说明

配置项说明默认值
ZADIG_API_HOSTZadig API 地址无，必填
ZADIG_API_TOKEN服务默认使用的 Zadig API Token无
MCP_HTTP_ENDPOINTStreamable HTTP 路径/mcp
MCP_SSE_ENDPOINTSSE 兼容事件流路径/sse
MCP_MESSAGE_ENDPOINTSSE 兼容消息路径/message
MCP_ALLOWED_ORIGINS允许访问的 Web 应用 Origin，多个值以逗号分隔空
MCP_SESSION_IDLE_TTLStreamable HTTP 会话空闲回收时间，使用 Go duration 格式30m
MCP_TRUSTED_PROXIES可信反向代理的 CIDR/IP 列表，用于审计时识别客户端 IP空
MCP_AUDIT_ENABLED是否启用审计日志，设为 true 时启用false

启用审计后，建议将 MCP_AUDIT_OUTPUT 设为 file，并使用 MCP_AUDIT_PATH 指定日志文件。MCP_AUDIT_BODY_MODE 支持 off、hash、redacted、raw；raw 会记录原始业务数据，仅建议临时排障使用。

仅当服务确实部署在反向代理之后时，才配置 MCP_TRUSTED_PROXIES，并仅填写实际 Ingress 或负载均衡器的出口 IP/最小 CIDR。不要将整个私网网段设为可信代理，否则审计中的客户端 IP 可能被伪造。

# SSE

SSE 是为旧客户端保留的兼容接入方式。服务端不应使用已弃用的 -t sse；请按以下示例以 -t http 启动服务，并通过 /sse 和 /message 提供兼容服务。

# 部署

在 Zadig 中将以下 YAML 作为服务配置加入环境。与 Streamable HTTP 部署相比，SSE 部署同样使用 http transport；差异仅在于客户端访问 /sse。请按实际环境修改地址、镜像、域名和 Ingress Class。

apiVersion: v1
kind: ConfigMap
metadata:
  name: zadig-mcp-sse-config
  labels:
    app: zadig-mcp-sse
data:
  ZADIG_API_HOST: "https://your-zadig.com"
  MCP_TRANSPORT_TYPE: "http"
  MCP_LISTEN_ADDR: "0.0.0.0:3000"
  MCP_HTTP_ENDPOINT: "/mcp"
  MCP_SSE_ENDPOINT: "/sse"
  MCP_MESSAGE_ENDPOINT: "/message"
  MCP_ALLOWED_ORIGINS: ""
  MCP_AUDIT_ENABLED: "false"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: zadig-mcp-sse
  labels:
    app: zadig-mcp-sse
spec:
  replicas: 1
  selector:
    matchLabels:
      app: zadig-mcp-sse
  template:
    metadata:
      labels:
        app: zadig-mcp-sse
    spec:
      containers:
        - name: zadig-mcp
          image: koderover.tencentcloudcr.com/koderover-public/zadig-mcp:0.2.0
          imagePullPolicy: IfNotPresent
          args:
            - "-t"
            - "$(MCP_TRANSPORT_TYPE)"
            - "-a"
            - "$(MCP_LISTEN_ADDR)"
          ports:
            - name: http
              containerPort: 3000
          envFrom:
            - configMapRef:
                name: zadig-mcp-sse-config
          readinessProbe:
            tcpSocket:
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            tcpSocket:
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 20
---
apiVersion: v1
kind: Service
metadata:
  name: zadig-mcp-sse
spec:
  selector:
    app: zadig-mcp-sse
  ports:
    - name: http
      port: 80
      targetPort: 3000
  type: ClusterIP
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: zadig-mcp-sse
  annotations:
    nginx.ingress.kubernetes.io/proxy-buffering: "off"
    nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
    nginx.ingress.kubernetes.io/proxy-http-version: "1.1"
spec:
  ingressClassName: your-ingress-class
  rules:
    - host: mcp.your-company.com
      http:
        paths:
          - path: /sse
            pathType: Prefix
            backend:
              service:
                name: zadig-mcp-sse
                port:
                  number: 80
          - path: /message
            pathType: Prefix
            backend:
              service:
                name: zadig-mcp-sse
                port:
                  number: 80
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

# 验证

  1. 在 Zadig 环境中确认 zadig-mcp-sse Pod 已就绪，服务日志没有启动错误。
  2. 确认 Ingress 已将 /sse 和 /message 转发到服务，并关闭响应缓冲。
  3. 在 SSE 客户端中配置下方地址，连接成功后调用 zadig_ping 或查询项目验证。

飞书 Aily 接入成功示例飞书 Aily 连接成功示例

# 使用

支持请求 Header 的客户端可配置：

{
  "mcpServers": {
    "zadig-mcp": {
      "url": "https://mcp.your-company.com/sse",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10

飞书 Aily 也支持该 SSE 兼容方式；使用仅支持填写 URL 的客户端时，可填写以下地址：

https://mcp.your-company.com/sse?api_token=your-token
1

以飞书 Aily 使用 SSE 兼容入口为例：

  1. 新增 MCP 服务。
  2. 填写上述 SSE 地址。
  3. 保存并验证连接；连接成功后，可通过对话查询 Zadig 项目、工作流和环境信息。

← OpenClaw 插件→

资源
教程
论坛
博客
公司
关于
客户故事
加入我们
联系我们
微信扫一扫
hello@koderover.com

© 2026 筑栈（上海）信息技术有限公司 沪 ICP 备 19000177 号 - 1