@monclair/mcp-cloud-client

MCP client para empleados Monclair. Conecta Claude Desktop (u otro cliente MCP compatible) al backend interno MCP-cloud de Monclair vía HTTP con Bearer auth.

Este paquete es interno — solo funciona con tokens emitidos por el panel-v2/admin de Monclair. Para el cliente B2C público (@monclair/mcp-server), ver el otro paquete.

1. Instalación

No requiere instalación previa — Claude Desktop lo descarga con npx -y:

# Verificación manual desde la terminal (debería printear "MCP_AGENT_TOKEN env var requerido"):
npx -y @monclair/mcp-cloud-client

2. Configuración Claude Desktop

Agregá esto a claude_desktop_config.json:

{
  "mcpServers": {
    "monclair": {
      "command": "npx",
      "args": ["-y", "@monclair/mcp-cloud-client"],
      "env": {
        "MCP_CLOUD_URL": "https://api.monclair.com.ar/api/agents",
        "MCP_AGENT_TOKEN": "mc_agent_..."
      }
    }
  }
}

Path del config file por OS:

| OS | Path | | ------- | ----------------------------------------------------------------- | | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

Después de pegar, reiniciá Claude Desktop.

3. Env vars

| Variable | Default | Descripción | | ------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------ | | MCP_AGENT_TOKEN | (requerido) | Token mc_agent_* emitido por panel-v2 admin. Sin esto, el cliente no arranca. | | MCP_CLOUD_URL | https://api.monclair.com.ar/api/agents | Base URL del backend MCP-cloud. Sobrescribir para staging. | | MCP_CLIENT_TIMEOUT_MS | 120000 | Timeout por request HTTP. Los agents pueden tardar — 2min suele ser suficiente. | | MCP_CLIENT_DEBUG | false | Si true, log a stderr de discovery + invokes. Nunca log a stdout (rompe el JSON-RPC). |

4. Troubleshooting

"MCP_AGENT_TOKEN env var requerido"

No pasaste el token. Pediselo a tu admin Monclair (genera uno desde panel-v2/admin/mcp-tokens).

Error 401 ("Token inválido o revocado")

Tu token fue revocado o expiró. Pedile a tu admin que te regenere uno.

Error 429 ("Rate limit")

Demasiadas requests en poco tiempo. El cliente reintenta automáticamente respetando el header Retry-After. Si seguís viendo 429s después de varios minutos, hablar con el admin.

Timeout

Aumentá MCP_CLIENT_TIMEOUT_MS. Default es 2 minutos.

Claude Desktop dice "No tools available"

Posibles causas:

1. Kill switch global activo — el admin pausó todo el MCP-cloud. Esperá o consultá.
2. Tu token no tiene scope para ningún tool — pediselo al admin.
3. Network — verificá que tu equipo puede llegar a https://api.monclair.com.ar.

Para diagnosticar: activá MCP_CLIENT_DEBUG=true y abrí los logs de Claude Desktop:

| OS | Path | | ------- | ----------------------------------------------------------------- | | macOS | ~/Library/Logs/Claude/mcp-server-monclair.log | | Windows | %APPDATA%\Claude\logs\mcp-server-monclair.log | | Linux | ~/.config/Claude/logs/mcp-server-monclair.log |

5. Versionado

Semver. Cambios breaking en MAJOR. El paquete sigue el versionado del backend MCP-cloud v1.x.

| Cliente | Backend mínimo | | ------- | -------------- | | 1.x | 1.x |

6. Licencia

MIT.