zihin-ai/zihin-mcp

Proxy MCP stdio-to-HTTP para a plataforma Zihin.ai. Conecta clientes MCP ao Zihin MCP Server via HTTP.
Inicio rapido
macOS / Linux:
Windows (PowerShell):
> 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:
Claude Code
Adicione ao .mcp.json do projeto:
Ou via CLI (a variavel ZIHIN_API_KEY deve estar definida no shell):
Cursor
Instalacao em 1 clique (cole na barra de endereco do navegador ou rode open ' '):
Troque zhn_live_xxx pela sua key nas configuracoes do MCP depois de instalar. Ou adicione ao .cursor/mcp.json:
VS Code (Copilot)
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:
Windsurf
Adicione ao ~/.windsurf/mcp.json:
Gemini CLI
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):
A variavel ZIHIN_API_KEY deve estar definida no seu shell. Alternativamente, para definir inline:
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
| Variavel | Obrigatoria | Descricao |
|----------|-------------|-----------|
| ZIHIN_API_KEY | Sim | API Key do tenant (formato zhn_live_*, zhn_test_* ou zhn_dev_*) |
| ZIHIN_MCP_URL | Nao | URL do MCP Server (default: https://llm.zihin.ai/mcp) |
| ZIHIN_MCP_CALL_TIMEOUT_MS | Nao | Teto 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):
Opcoes: --client claude|cursor|windsurf|codex|all · --dir · --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 , idempotente) com o indice das skills em .zihin/skills/.