Meta Agent Tools
PT

Back to the catalog

Zihin

Chat with your Zihin.ai agents, list them and load platform skills from any MCP client.

Open source Repository Open in the app JSON README (API)

About

Chat with your Zihin.ai agents, list them and load platform skills from any MCP client.

Details

Kind
MCP servers
Topic
No topic detected
Publisher
ai.zihin
Origin
official
Category
ferramentas
Transport
http
Version
2.2.1
Open pull requests
1
Last push
2026-09-02T02:47:22Z
Repository state
ativo
Language
JavaScript
License
MIT
Added
2026-09-02 01:00:55
Updated
2026-09-02 01:00:55
Origin id
ai.zihin/mcp-server

README

# @zihin/mcp-server

Proxy MCP stdio-to-HTTP para a plataforma [Zihin.ai](https://zihin.ai). Conecta clientes MCP ao Zihin MCP Server via HTTP.

[![smithery badge](https://smithery.ai/badge/zihin/mcp)](https://smithery.ai/servers/zihin/mcp)
[![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)

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

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

[![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)

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

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

```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 (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:

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

```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, 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

More