Getting Started

Quickstart

Three doors, five minutes each. Every command and output on this page was run against api.cognitiondesk.com.

Before you start

A CognitionDesk account.
An API key, created in the dashboard under API Keys. Treat it like a password: it can edit your assistants.
Node.js 18 or newer for the MCP and npm doors.

Door 1 — Connect your agent over MCP

Your coding agent gets tools to create, edit and publish assistants, load knowledge and read usage, all under your API key.

Add the server

In Claude Code:

Shell

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

In Cursor, Windsurf or any other MCP client, add it to the client’s MCP config:

mcp.json

JSON

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

Check that it connects

Real output

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" means the server started and the key was accepted.

Ask your agent for something

For example, "list my CognitionDesk assistants". The agent calls list_assistants and answers with what your account has.

Several clients?

Put one key per client in COGNITIONDESK_ACCOUNTS and switch with use_account. Read tools also take an account argument to peek at another client without switching.

Shell

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

Door 2 — Embed the widget

A chat bubble on your client’s site, talking to one assistant.

Create the widget in the dashboard

Pick the assistant, add the domains the widget may run on, and turn it on. The dashboard gives you the widget ID and an embed key that only works for that assistant and those domains.

Paste the snippet before </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>

Open the page: the bubble loads, and the assistant answers in the chat.

Or install it from npm

For React, Vue or any 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);

Use the embed key, never your own API key

Whatever goes in the snippet is public: anyone can read it from the page source. The embed key can only chat with that one assistant from the allowed domains. Your personal API key can edit every assistant you own. A request from a domain that is not on the list gets a 403 (“This origin is not authorized to use this widget”).

Real output

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

Door 3 — Call the API

From your backend, with an API key in the x-api-key header.

Create an assistant

Name and model are required. Keep the id from the response.

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."
  }'

Real output

JSON

{"success":true,"data":{"id":"cp67mF9QsfobdOujniPW","name":"Quickstart demo","model":"gpt-4o-mini", … ,"status":"active"}}

Send a message and stream the answer

The body carries the whole conversation in messages. The answer arrives as Server-Sent Events; the text is in data of the events with 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" }
  }'

Real output

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", …}}}

Without streaming, POST to /chat-apiKeyAuth/chat with the same body; the text comes back in response.message. Prefer /stream when the assistant can ask the user to pick an option: /chat waits for the answer and can time out.

Or use @cognitiondesk/client

Same call, without parsing the 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);

Real output

Shell

$ node index.mjs
Yes, we offer flat tire repair services.

Next steps

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.