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

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

Capabilities

As capabilities disponiveis dependem do role da API Key, controlado server-side:

| Role | Tools | Resources | Prompts | |------|-------|-----------|---------| | admin | Todas | 3 | 3 | | editor | Todas (write guardado) | 3 | 3 | | member | Subset (consumer) | - | - |

O numero exato de tools 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 |

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

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