Connect Kayako to Claude: Automate Support and Knowledge Base Tasks

If you need to connect Kayako to Claude to automate support ticket triage, draft knowledge base articles, or manage complex customer service workflows, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Kayako's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Kayako to ChatGPT or explore our broader architectural overview on connecting Kayako to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling customer service ecosystem like Kayako is an engineering challenge. You have to handle API token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with strict rate limits. Every time Kayako updates an endpoint or changes a custom field definition, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Kayako, connect it natively to Claude, and execute complex support operations using natural language.

The Engineering Reality of the Kayako API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Kayako's APIs requires navigating several unique architectural constraints. You are not just integrating a flat ticketing system - you are integrating an event-driven platform with cases, posts, identities, and hierarchical knowledge bases.

If you decide to build a custom MCP server for Kayako, you own the entire API lifecycle. Here are the specific challenges you will face:

Complex Relational Structures (Cases vs. Posts) In Kayako, a support interaction is not a single "ticket" object containing all the text. The architecture is split between Cases (the overarching container) and Posts (the individual messages within the conversation). Furthermore, posts can originate from various Channels (e.g., MAIL, TWITTER, MESSENGER, HELPCENTER). If you want an AI agent to read a customer's message and reply, the model cannot simply update a ticket text field. It must fetch the case, fetch the posts associated with the case, and then make a specific POST request to the case reply endpoint, supplying the correct channel. Managing this relational state across multiple tool calls often leads to LLM hallucinations if the tool schemas are not perfectly explicit.

Fragmented Identity Management Kayako separates the concept of a User from their Identities. A single user might have multiple email identities, phone identities, and social identities (Twitter, Facebook) tied to their profile. When an AI agent needs to update a customer's contact information, it cannot just patch the user object; it must query the specific identity endpoint (e.g., /api/v1/identities/emails) and perform operations there. Teaching an LLM to navigate this fragmented identity model requires highly descriptive JSON schemas and precise tool naming conventions.

Handling Rate Limits and Backoff Kayako enforces strict rate limits on its API to prevent abuse. A common mistake developers make is attempting to build infinite retries into the MCP server itself.

Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When Kayako returns an HTTP 429 Too Many Requests error, Truto passes that error directly back to the caller (your MCP client). Truto normalizes upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - whether that is a LangGraph agent or Claude Desktop - is entirely responsible for reading these headers and implementing its own retry and backoff logic. Truto does not absorb these errors.

Creating the Kayako MCP Server

Truto eliminates the need to build a custom server by dynamically generating an MCP JSON-RPC 2.0 endpoint based on your connected Kayako account. This endpoint derives its tools directly from Kayako's API documentation and your environment's specific configuration.

You can create this MCP server using either the Truto UI or the API.

Method 1: Via the Truto UI

For teams managing integrations manually, the UI provides a quick way to generate a secure server URL.

1. Log into your Truto dashboard and navigate to the Integrated Accounts page.
2. Select your connected Kayako account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read methods only, or filter by specific tags like support).
6. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/abc123def...).

Method 2: Via the Truto API

For platform teams embedding AI capabilities, you can generate MCP servers programmatically. This is ideal when provisioning dedicated agent infrastructure for individual tenants.

Make an authenticated POST request to the /integrated-account/:id/mcp endpoint:

const response = await fetch('https://api.truto.one/integrated-account/<kayako-account-id>/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <YOUR_TRUTO_API_KEY>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Kayako Support Operations MCP",
    config: {
      methods: ["read", "write"],
      tags: ["cases", "knowledge_base"]
    },
    expires_at: null
  })
});
 
const mcpServer = await response.json();
console.log("Your MCP Server URL:", mcpServer.url);

The returned url contains a secure, cryptographically hashed token that embeds the account context. This URL is the only configuration your MCP client needs.

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, connecting it to Claude is a straightforward process. You can do this through the Claude user interface or via a manual configuration file, depending on whether you are using the desktop application or a managed workspace.

Method A: Via the Claude UI

If your organization uses Claude Enterprise or Team plans, you can add custom connectors directly in the interface.

1. In Claude, navigate to Settings → Integrations (or Connectors depending on your plan tier).
2. Click Add MCP Server (or Add Custom Connector).
3. Paste the Truto MCP URL you generated in the previous step.
4. Click Add. Claude will instantly execute the initialize handshake and load all available Kayako tools.

(Note: If you are using ChatGPT instead, the process is similar: go to Settings → Apps → Advanced settings, enable Developer mode, and add the Truto MCP URL under the Custom Connectors section).

Method B: Via Manual Configuration File (Claude Desktop)

If you are running Claude Desktop locally for development, you must add the server to your claude_desktop_config.json file. Because Truto MCP servers use HTTP POST for communication, we use the official @modelcontextprotocol/server-sse wrapper to proxy the connection.

Open your configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the following:

{
  "mcpServers": {
    "kayako_prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/<YOUR_TRUTO_TOKEN>"
      ]
    }
  }
}

Restart Claude Desktop. The application will execute the tools/list JSON-RPC method against the Truto edge router, parse the JSON Schemas, and surface the Kayako operations as natural language tools.

High-Leverage Hero Tools for Kayako

Truto automatically generates tools based on the available resource methods in the Kayako API. When Claude executes a tool, all arguments (query parameters and body payloads) are supplied in a single flat JSON namespace. Truto's edge router automatically splits these arguments into the correct locations based on the integration's schemas.

Here are 6 of the highest-leverage tools available for Kayako.

list_all_kayako_cases

Retrieves a paginated list of conversations ordered by updated time. This is the foundation for any triage agent.

Usage note: Truto automatically enhances this tool's schema with limit and next_cursor properties, explicitly instructing the LLM to pass cursor values back unchanged for reliable pagination.

"Fetch the latest 20 open cases in Kayako. Tell me which ones have breached their SLA metrics and need immediate attention."

get_single_kayako_case_by_id

Fetches the complete metadata for a specific conversation, including custom fields, assignee data, and priority status.

Usage note: The id parameter is automatically injected as a required property in the schema, allowing Claude to seamlessly fetch individual records.

"Get the details for Kayako case ID 8492. Who is the assigned agent, and what is the current priority level?"

kayako_cases_create_reply

Adds a new reply post to an existing conversation. This is the primary method for communicating with customers via API.

Usage note: Because of the flat argument namespace, Claude simply provides { "case_id": 123, "contents": "Hello", "channel": "MAIL" }. Truto routes case_id to the URL path and contents/channel to the request body.

"Draft a polite response to case ID 8492 explaining that our engineering team is investigating the outage. Use the MAIL channel."

list_all_kayako_articles

Searches and retrieves articles from the Kayako Help Center. This is essential for agents attempting to solve customer queries using existing documentation.

Usage note: This tool supports filtering by section_id, tags, or raw query strings, allowing Claude to perform targeted knowledge base lookups.

"Search the Kayako help center for articles tagged with 'billing-faq'. Summarize the refund policy based on those articles."

create_a_kayako_article

Drafts a new Help Center article. Collaborators can only create articles with DRAFT status, enforcing a human-in-the-loop review process before publication.

Usage note: The LLM must supply the titles and contents objects. Truto ensures the payload matches Kayako's specific locale-mapping requirements.

"Take the resolution summary from case ID 8492 and draft a new Kayako Help Center article titled 'How to reset a stuck SSO session'. Keep it in draft status."

list_all_kayako_user_activities

Retrieves the historical timeline of a user's interactions across the Kayako instance, ordered by creation date.

Usage note: This is highly valuable for providing the LLM with customer context before it drafts a reply, preventing tone-deaf responses to frustrated users.

"Pull the activity history for user ID 405. Have they submitted any other critical tickets in the last 30 days?"

(For the complete inventory of available operations, schemas, and required parameters, refer to the Kayako integration page.)

Workflows in Action

Once connected, Claude can chain multiple Kayako tools together to execute complex, multi-step operations. Here are two real-world examples.

Scenario 1: Automated Ticket Triage and Response

A customer success manager wants Claude to handle the initial triage of incoming support emails, checking if the answer exists in the knowledge base before escalating.

"Check our recent open Kayako cases. If you find any asking about 'API rate limits', search the knowledge base for an answer. If you find one, reply to the customer with the link and mark the case priority as Low. If you don't find one, escalate the case priority to High."

Tool Execution Sequence:

1. list_all_kayako_cases - Claude retrieves a list of recent cases, filtering for status "Open".
2. list_all_kayako_articles - Identifying a case asking about rate limits, Claude searches the help center for relevant articles.
3. kayako_cases_create_reply - Finding an article, Claude drafts a response to the customer containing the link.
4. update_a_kayako_case_by_id - Claude patches the case record, lowering the priority to reflect that a documented solution was provided.

sequenceDiagram
    participant User as CSM
    participant Claude as Claude Desktop
    participant MCP as Truto MCP Server
    participant Upstream as Kayako API

    User->>Claude: "Triage rate limit tickets..."
    Claude->>MCP: Call list_all_kayako_cases()
    MCP->>Upstream: GET /api/v1/cases
    Upstream-->>MCP: Returns open cases
    MCP-->>Claude: JSON array of cases
    Claude->>MCP: Call list_all_kayako_articles(query="rate limit")
    MCP->>Upstream: GET /api/v1/articles
    Upstream-->>MCP: Returns article IDs and URLs
    MCP-->>Claude: JSON array of articles
    Claude->>MCP: Call kayako_cases_create_reply(case_id=102, contents=..., channel="MAIL")
    MCP->>Upstream: POST /api/v1/cases/102/reply
    Upstream-->>MCP: Confirmation
    MCP-->>Claude: Success
    Claude->>MCP: Call update_a_kayako_case_by_id(id=102, priority="Low")
    MCP->>Upstream: PUT /api/v1/cases/102
    Upstream-->>MCP: Updated case
    MCP-->>Claude: Success
    Claude-->>User: "I replied to case 102 with the rate limit documentation and lowered its priority."

Scenario 2: Support-Driven Documentation Drafting

A technical writer wants to turn a complex, newly resolved support ticket into a permanent Help Center article.

"Read the full thread for Kayako case ID 9920. Extract the root cause and the step-by-step fix provided by the agent. Use that to draft a new Help Center article in section 45, and leave it in draft status for my review."

Tool Execution Sequence:

1. get_single_kayako_case_by_id - Claude fetches the core metadata of the case to understand the subject and context.
2. list_all_kayako_case_posts - Claude iterates through the conversation thread to find the agent's resolution message.
3. create_a_kayako_article - Claude structures the extracted information into a clean Markdown document and submits it to the knowledge base as a draft.

Security and Access Control

Giving an LLM access to your entire Kayako instance is a significant security decision. Truto's MCP architecture provides several layers of access control to restrict what the model can do:

• Method Filtering: You can restrict a server to specific operation types by configuring the methods array during creation. For example, setting methods: ["read"] ensures Claude can only execute get and list operations, preventing it from accidentally updating cases or modifying users.
• Tag Filtering: You can scope tools by functional area using tags. If you only want Claude to access the knowledge base, you can pass tags: ["articles", "help_center"]. Tools without these tags (like billing or user management) will simply not exist in the server.
• Time-to-Live (TTL): By setting the expires_at property, you can create ephemeral MCP servers. Once the timestamp is reached, the server is automatically cleaned up by distributed edge alarms, making this ideal for temporary contractor access or limited-duration automated workflows.
• Dual Authentication (require_api_token_auth): By default, the cryptographically hashed MCP URL is the only authentication required. For zero-trust environments, you can enable require_api_token_auth: true. This forces the MCP client to also send a valid Truto API token in the Authorization header, ensuring that possession of the URL alone is not enough to access your data.

Summary

Building a reliable AI integration against Kayako requires more than just formatting a few JSON payloads. You must navigate fragmented conversational architectures, handle strict pagination schemas, and respect the API's rate limit boundaries. By leveraging a managed MCP server, you offload the entire infrastructure burden—from dynamic tool generation to token management—allowing you to focus entirely on designing the agent workflows that drive value for your support team.

If you are ready to automate your Kayako workflows without writing integration code, talk to us about Truto's SuperAI MCP Servers.