Zihin

ai.zihin由 zihin.ai 發布官方發布者v2.2.2更新於 Oct 28, 2026

Chat with your Zihin.ai agents, list them and load platform skills from any MCP client.

已驗證Streamable HTTP可網頁執行開發者工具AI 與機器學習

概覽

AI 產生的概覽

把 MCP 用戶端連接到 Zihin.ai 平台，讓助理與你的代理對話、列出代理並載入平台技能。

可以做什麼
  • 與 Zihin.ai 代理對話，支援跨輪次的對話延續
  • 列出租戶下的代理以及可用的 LLM 模型目錄
  • 讀取 schema 範本與各類型 payload 的正式 JSON Schema 契約
  • 以資源形式載入流程化技能（建立代理、工具、觸發器、診斷、治理）
  • 使用內建提示完成建立代理、為代理新增工具、設定 webhook 觸發器
  • 把技能安裝成用戶端原生格式（Claude Code、Cursor、Windsurf、Codex）
適用情境
適合已在使用 Zihin.ai 代理、希望在 Claude Desktop、Cursor、VS Code、Codex 等 MCP 用戶端裡直接與代理對話、檢視其設定或取得操作指引的情境。它只是代理，可用功能取決於 API Key 的角色。
執行需求
需要從 Zihin 主控台取得的 API Key，放在 ZIHIN_API_KEY 環境變數中（遠端端點使用 X-Api-Key 標頭）。本機執行需 Node.js 20 以上版本並透過 npx 啟動，且能連線到 Zihin MCP 伺服器。可選設定 ZIHIN_MCP_URL 與 ZIHIN_MCP_CALL_TIMEOUT_MS。
安裝前請注意
API Key 可存取整個租戶，其角色（admin、editor、member）決定會暴露哪些工具，admin 金鑰包含寫入操作，請勿放入共用設定。代理對話會消耗租戶真實的 LLM 用量，整合測試也會發出兩次真實對話。工具呼叫上限約 5 分鐘，逾時的輪次會被取消而非排隊。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Zihin，將其新增到工作區。
  2. 連接 X-Api-Key 憑證。它們會被私密儲存，絕不會在公開頁面上展示。
  3. 為需要使用其工具的對話啟用該服務。

Web executable，透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式，或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南，先向你展示發布者、端點和登入方式，經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/ai.zihin%2Fmcp-server/install.md，並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前，先告訴我它的發布者、端點和登入方式，等我確認。不要把 API 金鑰寫進命令或我會提交的檔案；問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

{
  "mcpServers": {
    "zihin": {
      "type": "http",
      "url": "https://llm.zihin.ai/mcp",
      "headers": {
        "X-Api-Key": "<YOUR_API_KEY>"
      }
    }
  }
}

README

@zihin/mcp-server

Proxy MCP stdio-to-HTTP para a plataforma Zihin.ai. Conecta clientes MCP ao Zihin MCP Server via HTTP.

[smithery badge] [zihin-mcp MCP server]

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

Inicio rapido

macOS / Linux:

bash
ZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server

Windows (PowerShell):

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

Na pratica, a maioria dos clientes MCP (Claude Desktop, Cursor, etc.) define a variavel automaticamente via bloco "env" na configuracao — nao e necessario definir manualmente no shell.

Configuracao

Claude Desktop

Adicione ao claude_desktop_config.json:

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

Claude Code

Adicione ao .mcp.json do projeto:

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

Ou via CLI (a variavel ZIHIN_API_KEY deve estar definida no shell):

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

Cursor

Instalacao em 1 clique (cole na barra de endereco do navegador ou rode open '<link>'):

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

Troque zhn_live_xxx pela sua key nas configuracoes do MCP depois de instalar. Ou adicione ao .cursor/mcp.json:

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

VS Code (Copilot)

[Install in VS Code]

O botao abre o VS Code com a config pronta (troque zhn_live_xxx pela sua key). Manual: comando MCP: Add Server ou .vscode/mcp.json:

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

Windsurf

Adicione ao ~/.windsurf/mcp.json:

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

Gemini CLI

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

A extensao pede a API Key na instalacao (fica no keychain) e instala o MCP + contexto. Config manual: ver "Outros clientes MCP".

Codex (OpenAI)

Adicione ao ~/.codex/config.toml (ou .codex/config.toml no projeto):

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

A variavel ZIHIN_API_KEY deve estar definida no seu shell. Alternativamente, para definir inline:

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

Outros clientes MCP

Qualquer cliente que suporte o protocolo MCP via stdio pode usar este pacote. O padrao de configuracao e o mesmo: executar npx -y @zihin/mcp-server com a variavel ZIHIN_API_KEY definida.

Variaveis de ambiente

VariavelObrigatoriaDescricao
ZIHIN_API_KEYSimAPI Key do tenant (formato zhn_live_*, zhn_test_* ou zhn_dev_*)
ZIHIN_MCP_URLNaoURL do MCP Server (default: https://llm.zihin.ai/mcp)
ZIHIN_MCP_CALL_TIMEOUT_MSNaoTeto de tempo de um tools/call, em milissegundos (default: 300000, 5 min; faixa aceita: 1000–1800000). O server tem deadline proprio por canal (defaults de chat 150s, builder 180s e demais canais 240s, sujeitos ao teto operacional do servidor) — o default deixa o server responder o erro diagnosticavel antes de o proxy cortar. As skills do backend 2026.10.5 informam teto operacional de 180s para os canais externos, incluindo chat_with_agent; esse valor depende da configuracao do servidor. Acima de ~300s o fetch do Node (undici) pode cortar antes, com timeout proprio de headers/body.

Como funciona

O pacote atua como um proxy transparente entre o cliente MCP local (via stdio) e o Zihin MCP Server (via HTTP):

  • Todas as tools, resources e prompts sao descobertos automaticamente do server
  • Auth, RBAC e tenant isolation sao enforced server-side via API Key
  • O role (admin/editor/member) e determinado pela API Key

Skills — deixe seu IDE especialista no Zihin

O servidor expoe 6 skills (playbooks procedurais: criar agente, tools, triggers, diagnostico, governanca) como resources zihin://skills/*, para os roles que enxergam resources (ver Capabilities). Nada precisa ser instalado, mas o corpo da skill nao e entregue sozinho: o client (ou o modelo) precisa consulta-lo com resources/read.

Para instalar tambem no formato NATIVO do seu client (ativacao automatica por contexto):

bash
# 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 cursorZIHIN_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

Opcoes: --client claude|cursor|windsurf|codex|all · --dir <raiz-do-projeto> · --global (so claude, instala em ~/.claude/skills) · --bundled (offline).

As skills sao buscadas do server vivo (sempre atualizadas). Se a busca falhar (rede, server fora do ar, key recusada) ou voltar vazia, o comando instala as copias empacotadas no npm — as mesmas do --bundled, congeladas na data da release. Na falha ele imprime um aviso; nos dois casos a saida informa a fonte usada (fonte: server ou fonte: bundled). Sem ZIHIN_API_KEY e sem --bundled nao ha fallback: o comando encerra com erro. No Codex, um bloco gerenciado e inserido no AGENTS.md (entre <!-- zihin-skills:start/end -->, idempotente) com o indice das skills em .zihin/skills/.

Plugin Claude Code (MCP + skills em um comando)

bash
claude plugin marketplace add zihin-ai/zihin-mcpclaude plugin install zihin@zihin

O plugin instala o MCP server (via este pacote) + as 6 skills. Requer ZIHIN_API_KEY exportada no ambiente.

Capabilities

As capabilities disponiveis dependem do role da API Key, controlado server-side:

RoleToolsResourcesPrompts
adminTodas (88)193
editorLeitura (48 — writes nao sao listadas)193
memberSubset consumer (5)--

Contagens verificadas contra producao em 04/10/2026 (88 tools / 19 resources — 3 catalogos + 10 schemas + 6 skills / 3 prompts). O numero exato pode variar conforme o server evolui.

Resources disponiveis

URIDescricao
zihin://agentsLista de agentes do tenant
zihin://modelsCatalogo de modelos LLM disponiveis
zihin://schema-templatesTemplates de schema para configuracao
zihin://schemas/{tipo}Contrato formal (JSON Schema) de cada payload — o mesmo que o server valida (10 tipos)
zihin://skills/{slug}Playbooks procedurais (6 skills — ver secao Skills acima)

Prompts disponiveis

NomeDescricao
setup-agentCria um agente completo (agente + persona + tools + publicacao)
add-toolAdiciona uma tool a um agente existente
configure-webhookConfigura trigger webhook para um agente

Testes

87 testes: unitarios offline (classificacao de erros, teto de timeout, install-skills, verificador do registry, coerencia dos manifests do plugin) + integracao real contra o server de producao. Sem ZIHIN_API_KEY, so os offline rodam; com a key, a suite completa:

bash
ZIHIN_API_KEY=zhn_live_xxx npm test

Cobertura: validacao de API Key, tools (incluindo chat_with_agent com session tracking, continuidade e o contrato de saida — execution_id, cancelled, tools_used/tool_calls), resources, prompts, protocolo MCP (identidade espelhada + instructions), classificacao de erros (formas SDK v1 e v2) e o teto de tools/call conferido contra o deadline do server.

A suite de integracao faz DUAS chamadas reais a chat_with_agent (abertura da sessao e continuidade) — dois turnos de agente, com custo real de LLM no tenant. No CI ela roda apenas no workflow da tag v*.

Troubleshooting

"ERRO: ZIHIN_API_KEY nao definida"

Defina a variavel de ambiente antes de rodar:

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

"Falha ao conectar ao server"

  • Verifique sua conexao com a internet
  • Verifique se a API Key e valida e esta ativa
  • Se usar URL customizada, verifique ZIHIN_MCP_URL

"ERRO FATAL: API Key invalida ou revogada"

A API Key foi revogada ou desativada no painel Zihin. Gere uma nova key e atualize a configuracao do cliente MCP. Reinicie o processo apos a troca.

"A tool X passou do teto de 300s do proxy e foi abortada"

O proxy espera ate 5 minutos por um tools/call. Quando essa mensagem aparece, o limite atingido foi o do proxy, nao o do server — o trabalho foi cancelado no servidor (no dialeto 2026-07-28 o abort do request e o sinal de cancelamento), entao nao ha execucao orfa queimando token.

  • Turno de agente legitimamente longo: suba o teto com ZIHIN_MCP_CALL_TIMEOUT_MS (em milissegundos, faixa 1000–1800000). Acima de ~300s o proprio fetch do Node pode cortar antes.
  • Quem estourou primeiro foi o server (deadline por canal: defaults de chat 150s, builder 180s e demais canais 240s, sujeitos ao teto operacional do servidor): a mensagem que chega e outra, um erro TURN_TIMEOUT com execution_id e session_id — leve esses dois identificadores para o suporte, sao a correlacao com a execucao no servidor.
  • Cliente MCP tem timeout proprio, independente deste: se o host desistir antes, ele mostra o erro dele.

Tools nao aparecem no cliente

  • Reinicie o cliente MCP apos alterar a configuracao
  • Claude Desktop: verifique logs em ~/Library/Logs/Claude/mcp*.log (macOS) ou %APPDATA%\Claude\logs\mcp*.log (Windows)

Limitacoes

  • Turno longo tem teto: tools/call espera no maximo 5 min no proxy (configuravel — ver ZIHIN_MCP_CALL_TIMEOUT_MS), e o server tem deadline proprio por canal (defaults de chat 150s, builder 180s e demais canais 240s, sujeitos ao teto operacional do servidor). Turno que passa disso e cancelado, nao enfileirado.
  • Streaming: A tool chat_with_agent retorna a resposta completa de uma vez (sincrono). O protocolo MCP define que tools retornam um CallToolResult completo — nao ha suporte a streaming progressivo. Para feedback em tempo real durante execucao do agente, use o endpoint REST SSE (POST /api/v2/agents/:agent_id/stream).

Requisitos

  • Node.js >= 20
  • Compativel com macOS, Linux e Windows

Licenca

MIT

來源：README.md，提交 894373c

工具

0
該伺服器需要 API 金鑰等憑證，因此 SourceWeft 無法在沒有憑證的情況下讀取其工具，也未收錄。

版本歷史

2
  1. v2.2.2最新Oct 5, 2026
  2. v2.2.1Sep 16, 2026

評分

已滿足適用檢查項的 85%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分