CORTEX MCP Server

Prerequisites

1. A CORTEX account — sign up at cortex-ai.net.
2. An Airis bot provisioned for your workspace — ask your CORTEX super-admin to create one at /super-admin/airis-bots.
3. Your Cortex API key — the cortexApiKey shown on the Airis bot detail page. It is a 64-character hex string.

Quick start

Claude Code

Register the CORTEX MCP server in Claude Code once:

claude mcp add --transport http cortex \
  https://api.cortex-ai.net/api/mcp \
  --header "X-Airis-Key: YOUR_64_CHAR_KEY"

Replace YOUR_64_CHAR_KEY with the key from the Airis bot detail page. Claude Code stores the entry in ~/.claude.json — tools are available immediately in new sessions.

Cursor / other MCP clients

Any client that supports Streamable HTTP transport works. Add the server entry to your MCP config:

{
  "mcpServers": {
    "cortex": {
      "type": "http",
      "url": "https://api.cortex-ai.net/api/mcp",
      "headers": {
        "X-Airis-Key": "YOUR_64_CHAR_KEY"
      }
    }
  }
}

UAT environment

# Staging / UAT
claude mcp add --transport http cortex-uat \
  https://uat-api.cortex-ai.net/api/mcp \
  --header "X-Airis-Key: YOUR_UAT_KEY"

Verify the connection

Ask the AI to list your kanban boards to confirm tools are loaded:

> List my kanban boards using the cortex MCP server.

→ kanban.list_boards returns [{id, name, isDefault, visibility, url}]

Authentication

Every request must include the X-Airis-Key header. The server validates it against the database; on success, the organizationId is resolved from the bot row and injected into every tool handler — you never supply it in tool input.

POST /api/mcp HTTP/1.1
Host: api.cortex-ai.net
Content-Type: application/json
X-Airis-Key: <your-64-char-hex-key>

{"jsonrpc":"2.0","method":"tools/call","id":1,"params":{...}}

Tools overview

The server exposes 36 tools across 7 namespaces. All tools support both read and write operations. Every tool is stateless — the server constructs a fresh context per HTTP request.

kanban.* — Tasks & boards

Create, read, update, and move tasks across boards. Every task response includes a url field pointing to the canonical CORTEX UI page — send it verbatim, never fabricate a link.

chatbot.* — Chatbot configs

Read and update chatbot configurations, switch business context sources, and monitor active conversations.

knowledge.* — RAG knowledge files

Manage the vector knowledge base (PDF, DOCX, XLSX, TXT) that chatbots use for retrieval-augmented generation.

business_profile.* — Business identity

Read and upsert the org-level business profile. Chatbots with businessContextSource = 'inherit' pull from this profile automatically.

promotion.* — Promotion ladders

Promotion ladders define tiered offer escalation (percent-off, free gift, bundle, etc.) that PromotionStrategyAgent uses when negotiating with customers.

playbook.* — Sales playbook

Sales playbook snippets are reusable evidence and fact statements (warranty, testimonials, pricing justification, social proof) referenced by ObjectionHandlingAgent when composing rebuttals.

campaign.* — Customer campaigns

Create and manage recurring or one-shot customer broadcasts. The segment audience is described in natural language (e.g. "VIP customers who bought in the last 30 days") and resolved by SegmentResolutionAgent to a type-safe filter — never raw SQL.

Security

Troubleshooting