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

Related MCP server: OpenAPI to Model Context Protocol (MCP)

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

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:

O numero exato de tools pode variar conforme o server evolui.

Resources disponiveis

Prompts disponiveis

Testes

O projeto inclui 19 testes de integracao real contra o server de producao:

ZIHIN_API_KEY=zhn_live_xxx npm test

Cobertura: validacao de API Key, tools (incluindo chat_with_agent com session tracking), resources, prompts e protocolo MCP.

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.

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

• 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 >= 18

• Compativel com macOS, Linux e Windows

Licenca

MIT