MCP server

IntelliDesk speaks the Model Context Protocol, so AI assistants like Claude and Cursor can use your support agent: ask it what a customer would, search what it knows, and read its conversations and leads.

Connect

The server is at https://YOUR_APP/api/mcp (Streamable HTTP). It uses the same secret keys as the REST API: create one under API keys in the dashboard. The API keys page also shows this setup with your address filled in.

Claude Code

Terminal

claude mcp add --transport http intellidesk https://YOUR_APP/api/mcp \
  --header "Authorization: Bearer idk_live_…"

Cursor, VS Code and other clients that take a JSON config with headers (for Cursor, .cursor/mcp.json; for a Claude Code project, .mcp.json):

mcp.json

{
  "mcpServers": {
    "intellidesk": {
      "type": "http",
      "url": "https://YOUR_APP/api/mcp",
      "headers": { "Authorization": "Bearer idk_live_…" }
    }
  }
}

Clients without header support can go through a local bridge such as mcp-remote:

mcp.json

{
  "mcpServers": {
    "intellidesk": {
      "command": "npx",
      "args": ["mcp-remote", "https://YOUR_APP/api/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer idk_live_…" }
    }
  }
}

A key with MCP access can read your agent's conversations. Give it only the scopes it needs, limit it to one agent if you can, and revoke it under API keys when you're done.

Tools

The key's scopes decide which tools the assistant sees. agent_id is optional when the key can use only one agent.

Tool	Scope	What it does
list_agents	read	The agents this key can use, with their training status.
ask_agent	chat	Asks the agent a question as a customer would, and returns its answer with sources. Pass `conversation_id` from an earlier answer to continue.
search_knowledge	read	The best passages from the agent's trained knowledge for a `query` (`limit` 1 to 10).
list_conversations	read	Recent conversations, newest first (`limit` 1 to 50).
get_conversation	read	One conversation with its messages.
list_leads	read	Contact details visitors left, with what they asked about (`days` back, default 30).
list_knowledge_gaps	read	Questions the agent couldn't answer, most asked first: material for new Q&A.

Things to ask your assistant: “Which questions did our agent miss this week? Draft answers for the top five.”, “Summarize today's hot leads.”, “Ask our support agent how it answers a refund request for a damaged item.”

Details

JSON-RPC 2.0 over POST; protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.
120 requests a minute per key; over that, 429 with Retry-After.
A tool that fails returns a result with isError: true and the reason, so the assistant can read it.
ask_agent chats appear in Activity like any other, and use message credits the same way.

curl

curl https://YOUR_APP/api/mcp \
  -H "Authorization: Bearer $INTELLIDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"ask_agent","arguments":{"question":"What is the refund policy?"}}}'