@zihin/mcp-server

@zihin/mcp-server

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

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

Adicione ao .cursor/mcp.json:

{
  "mcpServers": {
    "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"
      }
    }
  }
}

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

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 (chat 150s, builder 180s, async 240s) — o default deixa o server responder o erro diagnosticavel antes de o proxy cortar. 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/* — todo client MCP ja as recebe automaticamente, sem instalar nada.

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 <raiz-do-projeto> · --global (so claude, instala em ~/.claude/skills) · --bundled (offline).

As skills sao buscadas do server vivo (sempre atualizadas). 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)

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:

Role	Tools	Resources	Prompts
admin	Todas (96)	20	3
editor	Leitura (52 — writes nao sao listadas)	20	3
member	Subset consumer (5)	-	-

Contagens verificadas contra producao em 31/08/2026 (96 tools / 20 resources — 3 catalogos + 11 schemas + 6 skills / 3 prompts). O numero exato pode variar conforme o server evolui.

Resources disponiveis

URI	Descricao
zihin://agents	Lista de agentes do tenant
zihin://models	Catalogo de modelos LLM disponiveis
zihin://schema-templates	Templates de schema para configuracao
zihin://schemas/{tipo}	Contrato formal (JSON Schema) de cada payload — o mesmo que o server valida (11 tipos)
zihin://skills/{slug}	Playbooks procedurais (6 skills — ver secao Skills acima)

Prompts disponiveis

Nome	Descricao
setup-agent	Cria um agente completo (agente + persona + tools + publicacao)
add-tool	Adiciona uma tool a um agente existente
configure-webhook	Configura trigger webhook para um agente

Testes

62 testes: unitarios offline (classificacao de erros, teto de timeout, install-skills) + 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 executa um turno REAL de agente (custo de LLM no tenant). No CI ela roda apenas no gate de publish.

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. 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: chat 150s, builder 180s, async 240s): 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 (chat 150s, builder 180s, async 240s). 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