@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:```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 ''):```
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)
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
| 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):```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 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)```bash
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 (88) | 19 | 3 |
| `editor` | Leitura (48 — writes nao sao listadas) | 19 | 3 |
| `member` | Subset 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
| 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 (10 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
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 / 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, faixa1000–1800000). Acima de ~300s o propriofetchdo 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_TIMEOUTcomexecution_idesession_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/callespera no maximo 5 min no proxy (configuravel — verZIHIN_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_agentretorna a resposta completa de uma vez (sincrono). O protocolo MCP define que tools retornam umCallToolResultcompleto — 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