Zihin

ai.zihinPublished by zihin.aiOfficial publisherv2.2.2Updated Oct 28, 2026

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

VerifiedStreamable HTTPWeb executableDeveloper ToolsAI & ML

Overview

AI-generated overview

Connects an MCP client to the Zihin.ai platform so an assistant can chat with your agents, list them, and load platform skills.

What you can do
  • Chat with Zihin.ai agents, including session continuity across turns
  • List the tenant's agents and the available LLM model catalog
  • Read schema templates and formal JSON Schema contracts for payload types
  • Load procedural skills (agent creation, tools, triggers, diagnostics, governance) as resources
  • Use built-in prompts to set up an agent, add a tool, or configure a webhook trigger
  • Install the skills into a client's native format (Claude Code, Cursor, Windsurf, Codex)
When to use it
Useful when you already work with Zihin.ai agents and want to talk to them, inspect their configuration, or get guided playbooks from inside Claude Desktop, Cursor, VS Code, Codex or another MCP client. It is a thin proxy, so what you can do depends on the role of your API key.
Requirements
A Zihin.ai API key in the ZIHIN_API_KEY environment variable (or the X-Api-Key header for the remote endpoint), obtained from the Zihin console. Local use needs Node.js 20 or newer via npx; network access to the Zihin MCP server. Optional ZIHIN_MCP_URL and ZIHIN_MCP_CALL_TIMEOUT_MS settings.
Before you install
The API key grants tenant access and its role (admin, editor, member) decides which tools are exposed, including write operations for admin keys; keep it out of shared configs. Agent turns consume real LLM usage on your tenant, and the integration test suite makes two real chat calls. Tool calls are capped at about 5 minutes and long turns are cancelled, not queued.

Installation

In SourceWeft

  1. Open Zihin in the dashboard and add it to a workspace.
  2. Connect X-Api-Key credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/ai.zihin%2Fmcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "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

Source: README.md at commit 894373c

Tools

0
This server asks for a credential such as an API key, so SourceWeft could not read its tools without one and has not indexed them.

Version history

2
  1. v2.2.2LatestOct 5, 2026
  2. v2.2.1Sep 16, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts