CognitionDesk LogoCognitionDesk
Getting Started

Inicio rápido

Tres puertas, cinco minutos cada una. Cada comando y cada salida de esta página se ejecutaron contra api.cognitiondesk.com.

Antes de empezar

  • Una cuenta de CognitionDesk.
  • Una API key, creada en el panel en API Keys. Tratala como una contraseña: puede editar tus asistentes.
  • Node.js 18 o más nuevo para las puertas de MCP y npm.

Puerta 1 — Conectá tu agente por MCP

Tu agente de código obtiene herramientas para crear, editar y publicar asistentes, cargar conocimiento y ver el consumo, todo con tu API key.

1

Agregá el servidor

En Claude Code:

Shell
claude mcp add cognitiondesk \
  -e COGNITIONDESK_API_KEY=YOUR_API_KEY \
  -- npx -y @cognitiondesk/mcp

En Cursor, Windsurf o cualquier otro cliente MCP, agregalo a la configuración MCP del cliente:

mcp.json
JSON
{
  "mcpServers": {
    "cognitiondesk": {
      "command": "npx",
      "args": ["-y", "@cognitiondesk/mcp"],
      "env": { "COGNITIONDESK_API_KEY": "YOUR_API_KEY" }
    }
  }
}
2

Comprobá que conecta

Salida real
Shell
$ claude mcp get cognitiondesk
cognitiondesk:
  Scope: Local config (private to you in this project)
  Status: ✔ Connected
  Type: stdio
  Command: npx
  Args: -y @cognitiondesk/mcp

"Connected" significa que el servidor arrancó y la key fue aceptada.

3

Pedile algo a tu agente

Por ejemplo, "lista mis asistentes de CognitionDesk". El agente llama a list_assistants y responde con lo que tiene tu cuenta.

¿Varios clientes?

Poné una key por cliente en COGNITIONDESK_ACCOUNTS y cambiá con use_account. Las herramientas de lectura también aceptan un argumento account para mirar otro cliente sin cambiar de cuenta.

Shell
COGNITIONDESK_ACCOUNTS='{"acme":"KEY_FOR_ACME","globex":"KEY_FOR_GLOBEX"}'

Puerta 2 — Embebé el widget

Una burbuja de chat en el sitio de tu cliente, conectada a un asistente.

1

Creá el widget en el panel

Elegí el asistente, agregá los dominios donde puede correr el widget y activalo. El panel te da el ID del widget y una embed key que sólo sirve para ese asistente y esos dominios.

2

Pegá el snippet antes de </body>

HTML
<script
  src="https://cdn.jsdelivr.net/npm/@cognitiondesk/widget@1/dist/widget.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-api-key="YOUR_EMBED_KEY">
</script>

Abrí la página: la burbuja carga y el asistente responde en el chat.

3

O instalalo desde npm

Para React, Vue o cualquier bundler:

Shell
npm install @cognitiondesk/widget
JavaScript
import CognitionDeskWidget from '@cognitiondesk/widget';

const widget = new CognitionDeskWidget({
  widgetId: 'YOUR_WIDGET_ID',
  apiKey: 'YOUR_EMBED_KEY',
});

await widget.mount(document.body);

Usá la embed key, nunca tu propia API key

Lo que va en el snippet es público: cualquiera lo lee en el código de la página. La embed key sólo puede chatear con ese asistente desde los dominios permitidos. Tu API key personal puede editar todos tus asistentes. Un pedido desde un dominio que no está en la lista recibe un 403 ("This origin is not authorized to use this widget").

Salida real
Shell
$ curl -X POST https://api.cognitiondesk.com/chat-apiKeyAuth/stream \
    -H "Origin: http://localhost:8765" -H "x-api-key: YOUR_EMBED_KEY" …
{"success":false,"message":"This origin is not authorized to use this widget"}   # 403

Puerta 3 — Llamá a la API

Desde tu backend, con una API key en el header x-api-key.

1

Creá un asistente

El nombre y el modelo son obligatorios. Guardá el id de la respuesta.

Shell
curl -X POST https://api.cognitiondesk.com/platform-api/assistants \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quickstart demo",
    "model": "gpt-4o-mini",
    "systemPrompt": "You are the support assistant of a demo bike shop. Answer in one short sentence."
  }'
Salida real
JSON
{"success":true,"data":{"id":"cp67mF9QsfobdOujniPW","name":"Quickstart demo","model":"gpt-4o-mini", … ,"status":"active"}}
2

Mandá un mensaje y recibí la respuesta en streaming

El body lleva la conversación entera en messages. La respuesta llega como Server-Sent Events; el texto está en data de los eventos con type "content".

Shell
curl -N -X POST https://api.cognitiondesk.com/chat-apiKeyAuth/stream \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "YOUR_ASSISTANT_ID",
    "messages": [{ "role": "user", "content": "Do you repair flat tires?" }],
    "userContext": { "platform": "api", "conversationId": "order-1234" }
  }'
Salida real
Shell
data: {"type":"tool_calls","data":[{"name":"document_search","args":{"query":"repair flat tires"}, …}]}

data: {"type":"tool_output","data":{"name":"document_search","content":"No relevant documents found …"}}

data: {"type":"content","data":"Yes, we offer flat tire repair services.", …}

data: {"type":"metadata","data":{"usage":{"model":"gpt-4o-mini-2024-07-18", …}}}

Sin streaming, hacé POST a /chat-apiKeyAuth/chat con el mismo body; el texto vuelve en response.message. Preferí /stream cuando el asistente puede pedirle al usuario que elija una opción: /chat espera esa respuesta y puede agotar el tiempo.

3

O usa @cognitiondesk/client

La misma llamada, sin parsear el stream:

index.mjs
JavaScript
// npm install @cognitiondesk/client
import { createCognitionDeskClient } from '@cognitiondesk/client';

const client = createCognitionDeskClient({
  backendUrl: 'https://api.cognitiondesk.com',
  apiKey: process.env.COGNITIONDESK_API_KEY,
});

const text = await client.invokeAssistantText({
  assistantId: process.env.ASSISTANT_ID,
  prompt: 'Do you repair flat tires?',
  userContext: { platform: 'my-app', conversationId: 'order-1234' },
});
console.log(text);
Salida real
Shell
$ node index.mjs
Yes, we offer flat tire repair services.

Siguientes pasos

MCP Server

Tools, guides and remote install.

Web Widget

Themes, React, Vue, WordPress, Shopify.

Chat API

Full Chat API reference.

API Keys

Scopes and restricting a key to one assistant.

Inicio rápido — CognitionDesk Docs