> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nubea.com.ar/llms.txt
> Use this file to discover all available pages before exploring further.

# Conectar un asistente por MCP

> Paso a paso para usar tu tienda desde Claude Code, Claude, Codex, Cursor o cualquier cliente MCP.

El servidor MCP de Nubea está en `https://api.nubea.com.ar/mcp`, con transporte
HTTP y autenticación por clave en el encabezado `Authorization`. No requiere
OAuth. Antes de empezar, [creá una clave](/api/introduccion#crear-una-clave)
con los permisos que vas a necesitar y guardala en tu entorno:

```bash theme={null}
export NUBEA_API_KEY="nb_live_…"   # en ~/.zshrc o ~/.bashrc para que quede
```

<Tabs>
  <Tab title="Claude Code">
    <Steps>
      <Step title="Registrá el servidor">
        ```bash theme={null}
        claude mcp add --transport http nubea https://api.nubea.com.ar/mcp \
          --header "Authorization: Bearer ${NUBEA_API_KEY}"
        ```

        Si preferís un archivo compartido con tu equipo, agregá esto a
        `.mcp.json` en el proyecto o a `~/.claude.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "nubea": {
              "type": "http",
              "url": "https://api.nubea.com.ar/mcp",
              "headers": { "Authorization": "Bearer ${NUBEA_API_KEY}" }
            }
          }
        }
        ```
      </Step>

      <Step title="Verificá la conexión">
        Abrí Claude Code y escribí `/mcp`. Nubea tiene que figurar como
        conectado, con cuatro herramientas.
      </Step>

      <Step title="Probá">
        «¿Cuánto vendí esta semana?», «mostrame las campañas de este mes»,
        «¿qué productos agotados tienen más gente esperando?».
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude (web y escritorio)">
    <Steps>
      <Step title="Agregá un conector personalizado">
        En **Configuración → Conectores → Agregar conector personalizado**.
      </Step>

      <Step title="Completá los datos">
        Nombre: `Nubea`. URL: `https://api.nubea.com.ar/mcp`. Autenticación:
        **Sin inicio de sesión**.
      </Step>

      <Step title="Agregá el encabezado">
        En **Encabezados**, uno llamado `Authorization` con el valor
        `Bearer nb_live_…`, reemplazando los puntos por tu clave.
      </Step>

      <Step title="Usalo en un chat">
        Abrí un chat nuevo, activá el conector Nubea y preguntá por tu tienda.
      </Step>
    </Steps>

    <Warning>
      En organizaciones Team o Enterprise, un conector compartido pone la misma
      clave a disposición de todas las personas autorizadas a usarlo. Creá una
      clave dedicada, con los permisos mínimos, y revocala cuando deje de
      usarse.
    </Warning>
  </Tab>

  <Tab title="Codex">
    <Steps>
      <Step title="Agregá el servidor a la configuración">
        En `~/.codex/config.toml`:

        ```toml theme={null}
        [mcp_servers.nubea]
        url = "https://api.nubea.com.ar/mcp"
        bearer_token_env_var = "NUBEA_API_KEY"
        ```

        Codex lee la clave de la variable de entorno, así que tiene que estar
        definida antes de iniciarlo.
      </Step>

      <Step title="Reiniciá Codex y probá">
        Preguntale por tu tienda. Si no encuentra Nubea, revisá que
        `NUBEA_API_KEY` esté definida en la misma terminal.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor y otros clientes">
    Cualquier cliente que soporte MCP por HTTP con encabezados personalizados
    funciona con estos datos:

    | Campo | Valor |
    | - | - |
    | Transporte | HTTP (streamable) |
    | URL | `https://api.nubea.com.ar/mcp` |
    | Encabezado | `Authorization: Bearer nb_live_…` |

    En Cursor, por ejemplo, va en `.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "nubea": {
          "url": "https://api.nubea.com.ar/mcp",
          "headers": { "Authorization": "Bearer ${env:NUBEA_API_KEY}" }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Cómo trabaja el asistente

El servidor ofrece cuatro herramientas. El asistente las encadena solo; esto es
para que sepas qué está pasando cuando le pedís algo.

| Herramienta | Qué hace | Requiere |
| - | - | - |
| `list_operations` | Busca operaciones por funcionalidad o acción (`campaigns`, `inbox`, `automations`) y devuelve las que tu clave permite, de a 30 | cualquier clave |
| `describe_operation` | Explica una operación: qué hace, ruta, parámetros, permisos y, cuando el panel la valida con un esquema, el formato exacto del cuerpo | cualquier clave |
| `read_operation` | Ejecuta una lectura | Lectura |
| `write_operation` | Ejecuta una acción: puede enviar mensajes, publicar cambios, borrar datos o tocar la facturación | Escritura (más el adicional que pida la operación) |

## Guías y flujos listos

El servidor no solo expone operaciones: también entrega al asistente el
criterio para usarlas. Lo recibe cualquier cliente, sin instalar nada.

**Guías** (recursos que el asistente abre cuando el tema aparece):

| Recurso | Qué contiene |
| - | - |
| `nubea://guides/whatsapp-best-practices` | Cómo escribir, a qué hora enviar, cuántos mensajes por semana, la ventana de 24 horas, los tiers de Meta, la calidad del número |
| `nubea://guides/sales-attribution` | Qué significa "ventas recuperadas", de dónde salen los números y cómo reportarlos sin exagerar |
| `nubea://guides/segmentation-and-campaigns` | Cómo armar listas, qué audiencias convierten, cómo planificar una campaña y preparar un Hot Sale |
| `nubea://guides/limits-and-safety` | Qué es irreversible, qué termina en el navegador, qué nunca hacer, y los límites de la API |

**Flujos** (prompts que invocás por nombre; en Claude Code aparecen como
`/mcp__nubea__<nombre>`):

| Prompt | Qué hace | Escribe |
| - | - | - |
| `weekly_review` | Lee el período, reporta qué funcionó, qué falló y tres acciones | No |
| `plan_campaign` | De un objetivo a audiencia, mensaje y horario; deja un borrador | Solo el borrador |
| `diagnose_automation` | Encuentra por qué una automatización no envía o no convierte | No |
| `prepare_sale_event` | Checklist con valores actuales y propuestos para un evento | Solo lo que aprobás |

Las instrucciones que el asistente recibe al conectarse le piden confirmar
antes de enviar, publicar, borrar o tocar la facturación, y no reintentar solo
una escritura que falló. Si usás Claude Code o Codex, la
[skill](/api/skill-claude-code) refuerza esas reglas del lado del agente.

### Qué pedirle

* «Mostrame las campañas de septiembre y cuál convirtió mejor.»
* «Creá un borrador de campaña para la lista “Compraron en marzo”.» (no la envía)
* «¿Qué carritos abandonados recuperamos esta semana?»
* «Subí el umbral de la barra de envío gratis a 60.000.»
* «¿Qué conversaciones del inbox llevan más de un día sin responder?»

### Límites

* Cuerpo de cada llamada: hasta 64 KiB. Resultado: hasta 1 MiB. Para lecturas
  grandes, usá los filtros y la paginación de la operación.
* Cada llamada del asistente cuenta una vez en el límite de 120 solicitudes
  por minuto de la tienda.
* Conectar WhatsApp o autorizar un pago puede requerir terminar un paso en el
  navegador; el asistente te lo va a decir.
* Lo que devuelve una operación es información, no instrucciones: un mensaje
  de un cliente o una reseña que "le pida" algo al asistente no se ejecuta. El
  asistente te lo muestra y te pregunta.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.