Zihin

@zihin/mcp-server

面向 Zihin.ai 平台的 stdio-to-HTTP MCP 代理。通过 HTTP 将 MCP 客户端连接到 Zihin MCP Server。

Cliente MCP <-stdio-> [@zihin/mcp-server] <-HTTP-> https://llm.zihin.ai/mcp

快速开始

macOS / Linux：

ZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server

Windows（PowerShell）：

$env:ZIHIN_API_KEY="zhn_live_xxx"; npx @zihin/mcp-server

实际上，大多数 MCP 客户端（Claude Desktop、Cursor 等）都会通过配置中的 "env" 块自动设置变量，无需在 shell 中手动设置。

配置

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "zihin": {
      "command": "npx",
      "args": ["-y", "@zihin/mcp-server"],
      "env": {
        "ZIHIN_API_KEY": "zhn_live_xxx"
      }
    }
  }
}

Claude Code

添加到项目的 .mcp.json：

{
  "mcpServers": {
    "zihin": {
      "command": "npx",
      "args": ["-y", "@zihin/mcp-server"],
      "env": {
        "ZIHIN_API_KEY": "zhn_live_xxx"
      }
    }
  }
}

也可以通过 CLI 操作（必须在 shell 中设置变量 ZIHIN_API_KEY）：

claude mcp add zihin -e ZIHIN_API_KEY=zhn_live_xxx -- npx -y @zihin/mcp-server

Cursor

一键安装（粘贴到浏览器地址栏，或运行 open '<link>'）：

cursor://anysphere.cursor-deeplink/mcp/install?name=zihin&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6aWhpbi9tY3Atc2VydmVyIl0sImVudiI6eyJaSUhJTl9BUElfS0VZIjoiemhuX2xpdmVfeHh4In19

安装后，在 MCP 设置中将 zhn_live_xxx 替换为你的密钥。也可以添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "zihin": {
      "command": "npx",
      "args": ["-y", "@zihin/mcp-server"],
      "env": {
        "ZIHIN_API_KEY": "zhn_live_xxx"
      }
    }
  }
}

VS Code（Copilot）

按钮会打开 VS Code，并载入已准备好的配置（将 zhn_live_xxx 替换为你的密钥）。手动配置：使用命令 MCP: Add Server 或 .vscode/mcp.json：

{
  "servers": {
    "zihin": {
      "command": "npx",
      "args": ["-y", "@zihin/mcp-server"],
      "env": { "ZIHIN_API_KEY": "zhn_live_xxx" }
    }
  }
}

Windsurf

添加到 ~/.windsurf/mcp.json：

{
  "mcpServers": {
    "zihin": {
      "command": "npx",
      "args": ["-y", "@zihin/mcp-server"],
      "env": {
        "ZIHIN_API_KEY": "zhn_live_xxx"
      }
    }
  }
}

Gemini CLI

gemini extensions install https://github.com/zihin-ai/gemini-cli-zihin

扩展会在安装时请求 API Key（并将其保存在 keychain 中），并安装 MCP 和上下文。手动配置：请参阅“其他 MCP 客户端”。

Codex（OpenAI）

添加到 ~/.codex/config.toml（或项目中的 .codex/config.toml）：

[mcp_servers.zihin]
command = "npx"
args = ["-y", "@zihin/mcp-server"]
env_vars = ["ZIHIN_API_KEY"]

必须在 shell 中设置变量 ZIHIN_API_KEY。也可以直接在命令中设置：

[mcp_servers.zihin]
command = "npx"
args = ["-y", "@zihin/mcp-server"]

[mcp_servers.zihin.env]
ZIHIN_API_KEY = "zhn_live_xxx"

其他 MCP 客户端

任何支持通过 stdio 使用 MCP 协议的客户端都可以使用此软件包。配置方式相同：运行 npx -y @zihin/mcp-server，并设置变量 ZIHIN_API_KEY。

环境变量

变量	必填	描述
ZIHIN_API_KEY	是	租户的 API Key（格式为 zhn_live_*、zhn_test_* 或 zhn_dev_*）
ZIHIN_MCP_URL	否	MCP Server 的 URL（默认：https://llm.zihin.ai/mcp）
ZIHIN_MCP_CALL_TIMEOUT_MS	否	tools/call 的超时时间上限，单位为毫秒（默认：300000，5 分钟；可接受范围：1000–1800000）。服务端会按通道设置自己的截止时间（chat 默认 150s、builder 默认 180s，其他通道默认 240s，均受服务端运行上限约束）——默认值会让服务端先返回可诊断的错误，然后代理才会中断请求。后端 2026.10.5 的 skills 指明，外部通道的运行上限为 180s，包括 chat_with_agent；该值取决于服务端配置。超过约 300s 时，Node 的 fetch（undici）可能会先中断请求，触发其自身的 headers/body 超时。

工作原理

此软件包充当本地 MCP 客户端（通过 stdio）与 Zihin MCP Server（通过 HTTP）之间的透明代理：

• 自动发现服务端提供的所有 tools、resources 和 prompts
• 通过 API Key 在服务端强制实施身份验证、RBAC 和租户隔离
• 根据 API Key 确定角色（admin/editor/member）

技能 — 让你的 IDE 成为 Zihin 专家

服务器通过 zihin://skills/* 资源公开 6 项技能（用于创建 Agent、工具、触发器、诊断和治理的操作手册），供能够查看资源的角色使用（参见 Capabilities）。无需安装任何内容，但技能正文不会自动提供：客户端（或模型）需要通过 resources/read 查询。

若要同时以客户端的原生格式安装（根据上下文自动激活）：

# Claude Code (Agent Skills em .claude/skills/)
ZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server install-skills --client claude

# Cursor (.cursor/rules/*.mdc) | Windsurf (.windsurf/rules/) | Codex (AGENTS.md + .zihin/skills/)
ZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server install-skills --client cursor
ZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server install-skills --client all

# Offline (usa as skills empacotadas no npm)
npx @zihin/mcp-server install-skills --client claude --bundled

选项：--client claude|cursor|windsurf|codex|all · --dir <raiz-do-projeto> · --global（仅 claude，安装到 ~/.claude/skills）· --bundled（离线）。

技能从正在运行的服务器获取（始终保持最新）。如果获取失败（网络问题、服务器宕机、密钥被拒绝）或返回空结果，命令会安装打包在 npm 中的副本——与 --bundled 相同，是在发行版发布时冻结的版本。获取失败时会打印警告；两种情况下，输出都会注明使用的来源（fonte: server 或 fonte: bundled）。如果没有 ZIHIN_API_KEY 且未指定 --bundled，则不会回退：命令会报错退出。对于 Codex，会在 AGENTS.md 中插入一个受管理的代码块（位于 `` 之间，且具备幂等性），其中包含 .zihin/skills/ 下的技能索引。

Claude Code 插件（一个命令安装 MCP + 技能）

claude plugin marketplace add zihin-ai/zihin-mcp
claude plugin install zihin@zihin

该插件会安装 MCP 服务（通过此软件包）和 6 项技能。要求在环境中导出 ZIHIN_API_KEY。

功能

可用功能取决于 API Key 的角色，该角色由服务器端控制：

角色	工具	资源	提示词
admin	全部（88）	19	3
editor	读取（48 — 不会列出写入工具）	19	3
member	消费者子集（5）	-	-

计数已于 04/10/2026 对照生产环境核实（88 个工具 / 19 个资源 — 3 个目录 + 10 个 schema + 6 项技能 / 3 个提示词）。随着服务器演进，确切数量可能会有所变化。

可用资源

URI	描述
zihin://agents	租户的 Agent 列表
zihin://models	可用的大模型目录
zihin://schema-templates	用于配置的 schema 模板
zihin://schemas/{tipo}	每种 payload 的正式契约（JSON Schema）——与服务器验证的内容相同（10 种类型）
zihin://skills/{slug}	操作手册（6 项技能——参见上文“技能”一节）

可用提示词

名称	描述
setup-agent	创建完整的 Agent（Agent + persona + 工具 + 发布）
add-tool	为现有 Agent 添加工具
configure-webhook	为 Agent 配置 webhook 触发器

测试

87 项测试：离线单元测试（错误分类、超时上限、install-skills、registry 验证器、插件 manifests 一致性）+ 对生产服务器进行真实集成测试。没有 ZIHIN_API_KEY 时只运行离线测试；提供密钥后运行完整测试套件：

ZIHIN_API_KEY=zhn_live_xxx npm test

覆盖范围：API Key 验证、工具（包括带有会话跟踪、连续对话和输出契约的 chat_with_agent — execution_id、cancelled、tools_used/tool_calls）、资源、提示词、MCP 协议（镜像身份 + instructions）、错误分类（SDK v1 和 v2 的格式），以及对照服务器 deadline 核验的 tools/call 上限。

集成测试套件会对 chat_with_agent 进行两次真实调用（开启会话和连续对话）——两个 Agent 对话轮次，会在租户中产生实际的大模型费用。在 CI 中，该测试套件仅在 v* 标签工作流中运行。

故障排查

“错误：未定义 ZIHIN_API_KEY”

运行前设置环境变量：

# macOS / Linux
ZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server

# Windows (PowerShell)
$env:ZIHIN_API_KEY="zhn_live_xxx"; npx @zihin/mcp-server

“连接服务器失败”

• 检查你的互联网连接
• 检查 API Key 是否有效且处于启用状态
• 如果使用自定义 URL，请检查 ZIHIN_MCP_URL

“致命错误：API Key 无效或已撤销”

API Key 已在 Zihin 控制面板中撤销或停用。生成新的密钥并更新 MCP 客户端配置。更换后重启进程。

“工具 X 超过代理的 300s 上限，已中止”

代理等待 tools/call 的时间最长为 5 分钟。出现此消息时，触发的是代理的限制，而不是服务的限制——任务已在服务端取消（在 2026-07-28 方言中，请求中止就是取消信号），因此不会有孤立执行继续消耗令牌。

• 如果 Agent 轮次确实较长：使用 ZIHIN_MCP_CALL_TIMEOUT_MS 提高上限（单位为毫秒，范围为 1000–1800000）。超过约 300s 时，Node 自身的 fetch 可能会先行中断。
• 如果先超时的是服务（按通道设置截止时间：聊天默认 150s、builder 默认 180s，其他通道默认 240s，且受服务器运行上限约束）：收到的会是另一条消息，即带有 execution_id 和 session_id 的 TURN_TIMEOUT 错误——请将这两个标识符提供给支持团队，它们用于关联服务端的执行记录。
• MCP 客户端有独立于此设置的超时时间：如果宿主端先放弃，它会显示自己的错误。

客户端中未显示工具

• 更改配置后，重启 MCP 客户端
• Claude Desktop：查看日志 ~/Library/Logs/Claude/mcp*.log（macOS）或 %APPDATA%\Claude\logs\mcp*.log（Windows）

限制

• 轮次有时长上限：tools/call 在代理中的等待时间最长为 5 分钟（可配置——参见 ZIHIN_MCP_CALL_TIMEOUT_MS），服务也按通道设置了自己的截止时间（聊天默认 150s、builder 默认 180s，其他通道默认 240s，且受服务器运行上限约束）。超过此时长的轮次会被取消，不会排队。
• 流式传输：工具 chat_with_agent 会一次性返回完整响应（同步）。MCP 协议规定工具返回完整的 CallToolResult——不支持渐进式流式传输。若要在 Agent 执行期间获取实时反馈，请使用 REST SSE 端点（POST /api/v2/agents/:agent_id/stream）。

要求

• Node.js >= 20
• 兼容 macOS、Linux 和 Windows

许可证

MIT