MCP server

Install it locally

In Claude Code, one line:

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

In Claude Desktop, Cursor, Windsurf or any other client, add it to the MCP config:

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

Then check it:

$ 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 your key was accepted. Ask your agent to "list my CognitionDesk assistants" and it calls list_assistants.

The key comes from the dashboard, under API keys. Without one the server still starts, and every tool answers with a clear error instead of failing silently. API keys and scopes

Or use the hosted server

The same server speaks Streamable HTTP. Nothing to install: your key travels as a header on every request, and the server keeps no key of its own.

claude mcp add --transport http cognitiondesk \
  https://mcp.cognitiondesk.com/mcp \
  --header "x-api-key: YOUR_API_KEY"

Authorization: Bearer <key> works too. A request without a key is rejected at initialize with 401, so you find out while configuring the client, not on your first tool call.

Several clients, one server

If you run assistants for several clients, put every key in one server instead of running one server per client:

{
  "mcpServers": {
    "cognitiondesk": {
      "command": "npx",
      "args": ["-y", "@cognitiondesk/mcp"],
      "env": {
        "COGNITIONDESK_ACCOUNTS": "{\"acme\":\"KEY_FOR_ACME\",\"globex\":\"KEY_FOR_GLOBEX\"}",
        "COGNITIONDESK_ACTIVE_ACCOUNT": "acme"
      }
    }
  }
}

• get_connection_status lists the accounts the server holds, which one is active and which backend it talks to. It never prints a key.
• use_account switches the active account for everything that follows.
• Every read tool takes an optional account argument to look at another client for that one call. Writes always use the active account.
• Every response starts with account: <name>, so you never read the right answer from the wrong client.

The keyring only exists in local mode. In remote mode each request brings its own key, and an account argument is refused.

Guides and playbooks

The server ships the decisions people get wrong most, so your agent reads them before changing anything. Guides are MCP resources; playbooks are MCP prompts.

Every tool

Generated from the server itself, not written by hand: npm run tools:al-dia fails if this table and @cognitiondesk/mcp drift apart. Descriptions stay in English because that is what your agent reads.

@cognitiondesk/mcp · Version 0.11.1 · 128 tools

When it answers 403

The tool reached the platform and the platform said no. Two causes, and neither is fixed by editing the assistant:

• The key lacks the scope. Each tool needs one (assistants:*, knowledge:write…). Create a key with that scope, or ask list_scopes which one it is.
• PLAN_REQUIRED: the account is on a free plan. The MCP needs Pro or Business.