{
  "markdown": "# @zihin/mcp-server\n\nProxy MCP stdio-to-HTTP para a plataforma [Zihin.ai](https://zihin.ai). Conecta clientes MCP ao Zihin MCP Server via HTTP.\n\n[![smithery badge](https://smithery.ai/badge/zihin/mcp)](https://smithery.ai/servers/zihin/mcp)\n[![zihin-mcp MCP server](https://glama.ai/mcp/servers/zihin-ai/zihin-mcp/badges/score.svg)](https://glama.ai/mcp/servers/zihin-ai/zihin-mcp)\n\n```\nCliente MCP <-stdio-> [@zihin/mcp-server] <-HTTP-> https://llm.zihin.ai/mcp\n```\n\n## Inicio rapido\n\nmacOS / Linux:\n\n```bash\nZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server\n```\n\nWindows (PowerShell):\n\n```powershell\n$env:ZIHIN_API_KEY=\"zhn_live_xxx\"; npx @zihin/mcp-server\n```\n\n> 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.\n\n## Configuracao\n\n### Claude Desktop\n\nAdicione ao `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"zihin\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@zihin/mcp-server\"],\n      \"env\": {\n        \"ZIHIN_API_KEY\": \"zhn_live_xxx\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\nAdicione ao `.mcp.json` do projeto:\n\n```json\n{\n  \"mcpServers\": {\n    \"zihin\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@zihin/mcp-server\"],\n      \"env\": {\n        \"ZIHIN_API_KEY\": \"zhn_live_xxx\"\n      }\n    }\n  }\n}\n```\n\nOu via CLI (a variavel `ZIHIN_API_KEY` deve estar definida no shell):\n\n```bash\nclaude mcp add zihin -e ZIHIN_API_KEY=zhn_live_xxx -- npx -y @zihin/mcp-server\n```\n\n### Cursor\n\nInstalacao em 1 clique (cole na barra de endereco do navegador ou rode `open '<link>'`):\n\n```\ncursor://anysphere.cursor-deeplink/mcp/install?name=zihin&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6aWhpbi9tY3Atc2VydmVyIl0sImVudiI6eyJaSUhJTl9BUElfS0VZIjoiemhuX2xpdmVfeHh4In19\n```\n\nTroque `zhn_live_xxx` pela sua key nas configuracoes do MCP depois de instalar. Ou adicione ao `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"zihin\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@zihin/mcp-server\"],\n      \"env\": {\n        \"ZIHIN_API_KEY\": \"zhn_live_xxx\"\n      }\n    }\n  }\n}\n```\n\n### VS Code (Copilot)\n\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Zihin_MCP-0098FF?style=flat-square&logo=githubcopilot&logoColor=white)](https://vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22zihin%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40zihin%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22ZIHIN_API_KEY%22%3A%22zhn_live_xxx%22%7D%7D)\n\nO botao abre o VS Code com a config pronta (troque `zhn_live_xxx` pela sua key). Manual: comando\n`MCP: Add Server` ou `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"zihin\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@zihin/mcp-server\"],\n      \"env\": { \"ZIHIN_API_KEY\": \"zhn_live_xxx\" }\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdicione ao `~/.windsurf/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"zihin\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@zihin/mcp-server\"],\n      \"env\": {\n        \"ZIHIN_API_KEY\": \"zhn_live_xxx\"\n      }\n    }\n  }\n}\n```\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/zihin-ai/gemini-cli-zihin\n```\n\nA extensao pede a API Key na instalacao (fica no keychain) e instala o MCP + contexto. Config manual: ver \"Outros clientes MCP\".\n\n### Codex (OpenAI)\n\nAdicione ao `~/.codex/config.toml` (ou `.codex/config.toml` no projeto):\n\n```toml\n[mcp_servers.zihin]\ncommand = \"npx\"\nargs = [\"-y\", \"@zihin/mcp-server\"]\nenv_vars = [\"ZIHIN_API_KEY\"]\n```\n\nA variavel `ZIHIN_API_KEY` deve estar definida no seu shell. Alternativamente, para definir inline:\n\n```toml\n[mcp_servers.zihin]\ncommand = \"npx\"\nargs = [\"-y\", \"@zihin/mcp-server\"]\n\n[mcp_servers.zihin.env]\nZIHIN_API_KEY = \"zhn_live_xxx\"\n```\n\n### Outros clientes MCP\n\nQualquer 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.\n\n## Variaveis de ambiente\n\n| Variavel | Obrigatoria | Descricao |\n|----------|-------------|-----------|\n| `ZIHIN_API_KEY` | Sim | API Key do tenant (formato `zhn_live_*`, `zhn_test_*` ou `zhn_dev_*`) |\n| `ZIHIN_MCP_URL` | Nao | URL do MCP Server (default: `https://llm.zihin.ai/mcp`) |\n| `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. |\n\n## Como funciona\n\nO pacote atua como um **proxy transparente** entre o cliente MCP local (via stdio) e o Zihin MCP Server (via HTTP):\n\n- Todas as tools, resources e prompts sao descobertos automaticamente do server\n- Auth, RBAC e tenant isolation sao enforced server-side via API Key\n- O role (admin/editor/member) e determinado pela API Key\n\n## Skills — deixe seu IDE especialista no Zihin\n\nO 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.\n\nPara instalar tambem no formato NATIVO do seu client (ativacao automatica por contexto):\n\n```bash\n# Claude Code (Agent Skills em .claude/skills/)\nZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server install-skills --client claude\n\n# Cursor (.cursor/rules/*.mdc) | Windsurf (.windsurf/rules/) | Codex (AGENTS.md + .zihin/skills/)\nZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server install-skills --client cursor\nZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server install-skills --client all\n\n# Offline (usa as skills empacotadas no npm)\nnpx @zihin/mcp-server install-skills --client claude --bundled\n```\n\nOpcoes: `--client claude|cursor|windsurf|codex|all` · `--dir <raiz-do-projeto>` · `--global` (so claude, instala em `~/.claude/skills`) · `--bundled` (offline).\n\nAs 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/`.\n\n### Plugin Claude Code (MCP + skills em um comando)\n\n```bash\nclaude plugin marketplace add zihin-ai/zihin-mcp\nclaude plugin install zihin@zihin\n```\n\nO plugin instala o MCP server (via este pacote) + as 6 skills. Requer `ZIHIN_API_KEY` exportada no ambiente.\n\n## Capabilities\n\nAs capabilities disponiveis dependem do role da API Key, controlado server-side:\n\n| Role | Tools | Resources | Prompts |\n|------|-------|-----------|---------|\n| `admin` | Todas (96) | 20 | 3 |\n| `editor` | Leitura (52 — writes nao sao listadas) | 20 | 3 |\n| `member` | Subset consumer (5) | - | - |\n\nContagens 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.\n\n### Resources disponiveis\n\n| URI | Descricao |\n|-----|-----------|\n| `zihin://agents` | Lista de agentes do tenant |\n| `zihin://models` | Catalogo de modelos LLM disponiveis |\n| `zihin://schema-templates` | Templates de schema para configuracao |\n| `zihin://schemas/{tipo}` | Contrato formal (JSON Schema) de cada payload — o mesmo que o server valida (11 tipos) |\n| `zihin://skills/{slug}` | Playbooks procedurais (6 skills — ver secao Skills acima) |\n\n### Prompts disponiveis\n\n| Nome | Descricao |\n|------|-----------|\n| `setup-agent` | Cria um agente completo (agente + persona + tools + publicacao) |\n| `add-tool` | Adiciona uma tool a um agente existente |\n| `configure-webhook` | Configura trigger webhook para um agente |\n\n## Testes\n\n62 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:\n\n```bash\nZIHIN_API_KEY=zhn_live_xxx npm test\n```\n\nCobertura: 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.\n\n> A suite de integracao executa um turno REAL de agente (custo de LLM no tenant). No CI ela roda apenas no gate de publish.\n\n## Troubleshooting\n\n### \"ERRO: ZIHIN_API_KEY nao definida\"\n\nDefina a variavel de ambiente antes de rodar:\n\n```bash\n# macOS / Linux\nZIHIN_API_KEY=zhn_live_xxx npx @zihin/mcp-server\n\n# Windows (PowerShell)\n$env:ZIHIN_API_KEY=\"zhn_live_xxx\"; npx @zihin/mcp-server\n```\n\n### \"Falha ao conectar ao server\"\n\n- Verifique sua conexao com a internet\n- Verifique se a API Key e valida e esta ativa\n- Se usar URL customizada, verifique `ZIHIN_MCP_URL`\n\n### \"ERRO FATAL: API Key invalida ou revogada\"\n\nA 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.\n\n### \"A tool X passou do teto de 300s do proxy e foi abortada\"\n\nO 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.\n\n- 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.\n- 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.\n- Cliente MCP tem timeout proprio, independente deste: se o host desistir antes, ele mostra o erro dele.\n\n### Tools nao aparecem no cliente\n\n- Reinicie o cliente MCP apos alterar a configuracao\n- Claude Desktop: verifique logs em `~/Library/Logs/Claude/mcp*.log` (macOS) ou `%APPDATA%\\Claude\\logs\\mcp*.log` (Windows)\n\n## Limitacoes\n\n- **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.\n- **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`).\n\n## Requisitos\n\n- Node.js >= 20\n- Compativel com macOS, Linux e Windows\n\n## Licenca\n\nMIT\n",
  "bytes": 10968,
  "sha": "1a285f0c388c0f9bb093f3ad9684f6add2646ebe34f7583dd2e10c3dc969d10d",
  "repo_slug": "zihin-ai/zihin-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_zihin_mcp_server_38748878/readme"
}