Connect MCP

“Create a customer-support chat agent with two actors — Triage and Returns. Give Returns access to my Shopify integration. Deploy it.”

“Build a workflow that runs every morning at 9 AM, fetches new Stripe charges from the last 24 hours, and posts a summary to Slack.”

“Add a code step that reads every row of my Leads sheet and posts each qualified lead to #sales.”

“Read the Q3 summary in Workspace files and save a one-page version beside it.”

​

What you can do via MCP

​

Why this is useful

​

Getting started

​

1. Open API access in Workspace settings

​

2. Create a workspace API key

​

3. Copy the MCP config for your client

• Claude
• Cursor
• Codex
• curl (smoke test)

Claude Code — one-line registration:

claude mcp add-json cogniagent '{"type":"http","url":"https://embed.cogniagent.ai/mcp","headers":{"Authorization":"Bearer YOUR_WORKSPACE_API_KEY"}}'

Verify with /mcp in Claude Code.Claude Desktop — paste the block below into mcpServers in claude_desktop_config.json, then restart:

{
  "mcpServers": {
    "cogniagent": {
      "url": "https://embed.cogniagent.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_WORKSPACE_API_KEY"
      }
    }
  }
}

Paste into Cursor’s MCP servers config:

{
  "mcpServers": {
    "cogniagent": {
      "url": "https://embed.cogniagent.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_WORKSPACE_API_KEY"
      }
    }
  }
}

Add to Codex’s mcp_servers.toml:

[mcp_servers.cogniagent]
url = "https://embed.cogniagent.ai/mcp"
http_headers = { Authorization = "Bearer YOUR_WORKSPACE_API_KEY" }

Confirm the endpoint and key work before wiring up a real client — this lists every tool the MCP server exposes:

curl https://embed.cogniagent.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_WORKSPACE_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

​

4. Verify it’s working

“List my Chat & Voice Agents.”

​

A worked example — building Sales Triage by prompt

“Build a Sales Triage chat agent in my workspace. It should have three actors: a Triage actor that asks one qualifying question, a Product Specialist who answers product questions, and a Pricing Specialist who handles pricing. The agent should be in Responder mode. Set the global context to introduce Acme Inc., a SaaS company with two products: Acme Pro at $49/seat/month with a 14-day trial, and Acme Enterprise with SSO, SLAs, and a dedicated success manager. Wire routing so Triage hands off based on user intent — to Product Specialist for product questions, to Pricing Specialist for pricing questions. Add a widget channel and deploy it. Then run a test conversation to verify routing works.”

​

Discovering tools

• read_platform_guide — high-level guides for building Chat & Voice Agents (conversation flows), workflows (applications), integrations, focus modes.
• get_node_howto — per-node-type configuration shape.
• read_platform_guide with the topic workspace_files — how paths, @files/ mentions, limits, conflicts and the Trash work in Workspace files.

​

Tool surface, at a glance

​

Conditions on routes

{
  "activationPrompt": "When the user asks for a refund or to reverse a charge.",
  "activationCondition": {
    "type": "rule",
    "match": "all",
    "rules": [
      { "source": "param", "name": "user_role", "operator": "equals", "value": "manager" },
      { "source": "slot", "name": "order_id", "operator": "is_set" }
    ]
  }
}

• match: all (the default) or any. 1–10 rules.
• source: param (an Initial Parameter) or slot. name is the @param. / @slot. name.
• operator and value: equals, not_equals, contains take a string (up to 200 characters), a number or a boolean; greater_than, less_than take a number; in, not_in take a list of 1–50 strings; is_set, is_not_set take no value.
• Strings compare trimmed and ignoring case. A value that isn’t set fails every operator except is_not_set.

{
  "activationPrompt": "When the user needs help with their account, an order or a subscription.",
  "activationCondition": {
    "type": "ai",
    "prompt": "The visitor says they're already a customer, for example by mentioning their account or a past order."
  }
}

• prompt: 1–2000 characters, not blank. No other keys: match or rules next to "type": "ai" is invalid.
• Mentions: @param.<name> and @slot.<name> are replaced with their values before the check. Slot values and parameters from the page or the URL are marked as untrusted for the AI. validate_conversation_flow checks them like rules: an unknown parameter is an error, an unknown slot a warning.
• The AI answers at most once per user message, and only when the router needs that route. If it can’t decide, or anything fails or times out, the actor stays hidden. A failed check isn’t an answer, so it may run again later on the same message.
• AI conditions are advisory, not access control: the visitor writes the conversation the AI reads. Gate roles and permissions with a rule on a parameter the visitor can’t change (a widget link’s parameters, or a conversation started from a workflow or the API), never one from the page or the URL.
• In live voice, AI conditions aren’t checked, so the route stays closed. validate_conversation_flow warns about it on a live voice agent.

​

Custom actions

• list_integration_actions lists two more things beside an app’s actions:
  • customActions: the workspace’s saved custom actions of the app ({ key: "custom__…", name, call, inputs }). They work like catalog actions, and get_integration_action takes their key.
  • customRequest: whether any endpoint of the app can be called. { key: "__request", available: true, baseUrl?, target? } says where paths resolve; { available: false, reason } says why not.
• get_integration_action with the key __request returns the step’s configuration (externalAction: "__request" and an externalActionConfig of method, path, query, headers and body), the Python call integrations.<app>.request(...) and the rules.
• manage_custom_action creates, updates and deletes saved custom actions (op: create, update or delete). In a saved request, every {{…}} is an input, written {{args.<input>}}. An update reaches everything that uses the action on its next run; a delete makes the steps that use it fail with its name.
• On an integration entry in a Chat & Voice Agent (conversation flow) actor’s capabilities, customRequests: "read" or "write" turns on Custom API calls for that app. A saved custom action is granted like any action, by its custom__… key.

​

Safety guardrails

• A workspace API key is scoped to the workspace it was created in — it cannot reach agents or workflows in any other workspace.
• Destructive operations (delete, undeploy) require an explicit confirmation in the AI’s request — the server doesn’t infer.
• The Last used column on the API Access page lets you spot unused or stale keys and revoke them.

​

Limitations

• No bulk operations. The MCP server is designed for interactive authoring, not batch migrations. For bulk work, use the underlying API directly.
• No streaming chat with end-users. MCP is for building and operating agents and workflows. The actual user-facing conversations run on the channels you’ve configured.
• Token rotation. Tokens don’t auto-rotate. Treat them like any long-lived API key and rotate periodically.

​

Next