Zihin

@zihin/mcp-server

Converse com seus agentes de IA da [Zihin.ai](https://www.zihin.ai) e gerencie-os direto do seu IDE ou assistente — Claude, Cursor, VS Code, Codex, Gemini CLI ou qualquer cliente MCP.

Se este projeto for útil para você, uma ⭐ ajuda outras pessoas a encontrá-lo.

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

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

Em 30 segundos

1. Gere uma API Key no console da Zihin.
2. Registre o servidor no seu cliente — no Claude Code, por exemplo:

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

Claude Desktop, Cursor (1 clique), VS Code (1 clique), Windsurf, Gemini CLI e Codex: ver Configuracao.

1. Peça ao assistente: *"liste meus agentes Zihin"* ou *"converse com o agente X"*.

O que você pode fazer

• Conversar com agentes publicados (chat_with_agent, com continuidade de sessão).
• Criar e configurar agentes: persona, tools de API externa, MCP servers externos e publicação — com o prompt guiado setup-agent.
• Conectar canais e automações: triggers de webhook (WhatsApp, Slack, Teams, n8n), agendados e por e-mail.
• Governar: teto de gasto por agente, políticas de segurança e aprovação humana antes de ações sensíveis.
• Diagnosticar: métricas por agente, traces de execução e saúde do tenant.

Até 88 tools para uma key admin (ver Capabilities); o que cada key enxerga depende do role. Documentação completa: docs.zihin.ai · Site: www.zihin.ai

Inicio rapido

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

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:

{

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

Claude Code

Adicione ao .mcp.json do projeto:

{

"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):

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 ' '):

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:

{

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

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:

{

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

Windsurf

Adicione ao ~/.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

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):

[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:

[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

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):

# 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

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/.

Plugin Claude Code (MCP + skills em um comando)

claude plugin marketplace add zihin-ai/zihin-mcp

claude 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:

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

Prompts disponiveis

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:

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:

# 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

"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. Reini