This article documents every tool exposed by the LiveAgent MCP server, including the exact parameters each tool accepts and the exact fields it returns. The same tool set is available for both personal MCP connections and AI agent MCP connections.
Every tool returns a single JSON object. A call that succeeds returns the documented response, while a tool that has nothing to return answers with {"success": true}. A call that fails returns an error object, e.g. {"success": false, "error": "Not authorized to read this ticket"}.
Ticket read tools
Get ticket messages (get_ticket_messages)
Retrieves messages of a ticket, including notes by default. Limited to 20 messages per call — page through the rest with nextCursor.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
| since | No | Cursor from a previous tool call response, used to return next messages |
| types | No | Return only selected message types: email, chat, whatsapp, instant_message, note, or legacy_message. |
| dateFrom | No | Filter only messages added at or after specified time using RFC 3339 timestamp in UTC, e.g. 2026-07-08T10:00:00Z |
| dateTo | No | Filter only messages added at or before specified time using RFC 3339 timestamp in UTC, e.g. 2026-07-08T10:00:00Z |
| order | No | Sort response records, use desc (default) to list newest records first, or asc to list oldest records first. When since is used, the cursor's own sorting direction applies, and a conflicting order is rejected. |
Returns
| Field | Description |
|---|---|
| messages[].id | Message identifier. |
| messages[].text | Message body as plain text. |
| messages[].author | Who added the message: agent, customer, ai_agent, rule, or external_app. |
| messages[].authorId | Identifier of the author. |
| messages[].type | Message type: email, chat, whatsapp, instant_message, note or legacy_message. |
| messages[].createdAt | Datetime when the message was added, as an RFC 3339 timestamp, e.g. 2026-07-08T10:00:00+00:00. |
| messages[].attachments[] | Attachments of the ticket messages, each with id, fileName, contentType, size (bytes) and downloadUrl.The attachment content is never inlined in the result. downloadUrl is a short-lived, single-use link valid for 3 hours, consumed by the first successful download. |
| nextCursor | Cursor referring to the last returned message. Pass this as since parameter to retrieve next messages. Returns null when there are no more messages. |
Get ticket metadata (get_ticket_metadata)
Reads a ticket's properties.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
Returns
| Field | Description |
|---|---|
| id | Internal ticket ID. |
| code | Short human-readable ticket code, e.g. ABC-DEFGH-123, commonly shown in the agent panel. |
| subject | Ticket subject. |
| status | Current ticket status: new, open, answered, resolved, postponed, chatting, calling, closed, deleted or spam. |
| channel | Channel the ticket was created from: email, contact_button, contact_form, invitation, call, call_button, facebook, facebook_message, twitter, forum, suggestion, instagram, instagram_mention, viber, whatsapp, telegram. |
| departmentId | ID of the department the ticket belongs to. |
| departmentName | Name of the department the ticket belongs to. |
| assignedAgentId | ID of the agent the ticket is assigned to. null when the ticket is unassigned. |
| assignedAgentName | Assigned agent's display name. null when the ticket is unassigned. |
| tags | Names of the tags currently attributed to the ticket. |
| createdAt | Datetime when the ticket was created, as an RFC 3339 timestamp, e.g. 2026-07-08T10:00:00+00:00. |
| lastActivityAt | Datetime when the ticket last changed, as an RFC 3339 timestamp, e.g. 2026-07-08T10:00:00+00:00. |
Get ticket notes (get_ticket_notes)
Retrieves the internal notes of a ticket, newest first. Limited to 20 notes per call — page through the rest with nextCursor.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
| since | No | Cursor from a previous tool call response, used to return next notes |
Returns
| Field | Description |
|---|---|
| notes[].noteId | Note identifier. |
| notes[].text | Note body as plain text. |
| notes[].author.id | Identifier of the author. |
| notes[].author.name | Author display name. |
| notes[].author.type | Who added the note: agent, ai_agent, rule or external_app. |
| notes[].createdAt | Datetime when the note was added, as an RFC 3339 timestamp, e.g. 2026-07-08T10:00:00+00:00. |
| nextCursor | Cursor referring to the last returned note. Pass this as since parameter to retrieve next notes. Returns null when there are no more notes. |
Get tags (get_tags)
Lists every available tag in the account.
Parameters: none.
Returns
| Field | Description |
|---|---|
| tags[].id | Tag identifier, a 4-character alphanumeric code. |
| tags[].name | Tag name as shown in the agent panel. |
| tags[].isPublic | Denotes if the tag is visible outside the agent panel: true for public tags, false for internal ones. |
Search tickets (search_tickets)
Retrieves a list of tickets. Results are ordered by last change, newest first. Limited to 50 tickets per call.
Parameters
| Parameter | Required | Description |
|---|---|---|
| status | No | Filter only tickets in the selected statuses: new, open, answered, resolved, postponed, chatting or calling. Several statuses can be combined. When omitted, everything except deleted, closed and spam tickets is returned. |
| departmentId | No | Return only tickets in the selected department, as returned by list_departments. When omitted, tickets of every department are returned. |
| agentId | No | Return only tickets assigned to the selected agent, as returned by list_agents. When omitted, tickets of every agent are returned, assigned or not. |
| query | No | Return only tickets whose content matches this full-text phrase. When omitted, no text matching is applied. |
| limit | No | Maximum number of tickets to return, 10 by default, up to a maximum of 50. A higher value is quietly reduced to 50 rather than rejected. |
| cursor | No | Cursor from a previous tool call response, used to return the next page of results. |
Returns
| Field | Description |
|---|---|
| tickets[].id | Internal ticket ID. |
| tickets[].code | Short human-readable ticket code, e.g. ABC-DEFGH-123, commonly shown in the agent panel. |
| tickets[].subject | Ticket subject. |
| tickets[].status | Current ticket status. Any status can come back here, including the four the status filter does not accept: init, closed, deleted and spam. |
| tickets[].departmentId | ID of the department the ticket belongs to. |
| tickets[].assignedAgentId | ID of the agent the ticket is assigned to. null when the ticket is unassigned. |
| totalCount | Total number of matching tickets, not just those on this page. |
| nextCursor | Cursor referring to the last returned ticket, pass as cursor to retrieve the next page. Returns null when there are no more tickets. |
Note: there is no date, tag, customer or channel filter, and the sort order cannot be changed. See Known limitations for what to do instead. Note also that the department and the assigned agent come back as IDs only — resolve them with list_departments and list_agents.
List agents (list_agents)
Lists the agents in the account. Use it to resolve an agent ID before assigning a ticket, or to turn an assignedAgentId into a name and e-mail address.
Parameters
| Parameter | Required | Description |
|---|---|---|
| search | No | Return only agents whose name or e-mail address contains this text. When omitted, all agents are returned. |
Returns
| Field | Description |
|---|---|
| agents[].id | Agent identifier — this is what assign_ticket expects as agentId. |
| agents[].name | Agent display name. |
| agents[].email | Agent e-mail address. null when the agent has none. |
List departments (list_departments)
Lists the departments in the account, for routing and transfer decisions.
Parameters
| Parameter | Required | Description |
|---|---|---|
| search | No | Return only departments whose name contains this text. When omitted, all departments are returned. |
Returns
| Field | Description |
|---|---|
| departments[].id | Department identifier — this is what transfer_ticket expects as departmentId. |
| departments[].name | Department name. |
Ticket field tools
Get ticket field definitions (get_ticket_field_definitions)
Returns the custom ticket fields configured for the account, with the metadata needed to fill them in correctly. Archived definitions are excluded.
Parameters: none.
Returns
| Field | Description |
|---|---|
| definitions[].definitionId | Numeric definition ID, one of the two ways to address the field when writing a value. |
| definitions[].code | Stable string code of the field, usable as definitionCode instead of the numeric ID. |
| definitions[].name | Field label as shown in the agent panel. |
| definitions[].type | Field type, which decides the value parameter you use when writing: BOOLEAN, STRING, POSTAL_ADDRESS, LIST_SINGLE_VALUED or LIST_MULTI_VALUED. |
| definitions[].description | Help text configured for the field, as shown beside it in the agent panel. An empty string when none is set. |
| definitions[].checkboxDescription | Label shown next to the checkbox. Present on BOOLEAN definitions only. |
| definitions[].validation | Rule a value has to satisfy, present on STRING definitions only. Either {"kind":"PREDEFINED","format":…} with one of ALPHANUMERIC, ALPHANUMERIC_SPACE, DATE, DATE_REVERSE, DECIMAL, EMAIL, WHOLE_NUMBER, NUMERIC_STRING, INTERNATIONAL_PHONE, US_PHONE, IP_ADDRESS, TEXT, TIME, URL; or {"kind":"CUSTOM","regex":…} carrying a regular expression of your own. |
| definitions[].availableValues | Option labels a value can be chosen from. Present on LIST_SINGLE_VALUED and LIST_MULTI_VALUED definitions only. |
Get ticket field values (get_ticket_field_values)
Reads all custom field values stored on one ticket, each returned together with its definition metadata. Values whose definition has since been archived are still returned.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
Returns
| Field | Description |
|---|---|
| values[].fieldId | ID of this stored value — the handle delete_ticket_field_value expects. |
| values[].definitionId | Numeric ID of the definition this value belongs to. |
| values[].code | String code of the definition this value belongs to. |
| values[].name | Field label as shown in the agent panel. |
| values[].type | Field type, using the same values as get_ticket_field_definitions. |
| values[].value | The stored value, typed after the field: boolean for BOOLEAN; string for STRING and LIST_SINGLE_VALUED; array of strings for LIST_MULTI_VALUED; object with street, district, city, state, postalCode, country for POSTAL_ADDRESS. |
Set ticket field value (set_ticket_field_value)
Idempotent upsert of one custom field value: creates it when missing, updates it when present and different, does nothing when it already matches.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
| definitionId | One of the two | Numeric definition ID, as returned by get_ticket_field_definitions. Supply either this or definitionCode — never both, never neither. |
| definitionCode | One of the two | Stable string code of the field, as returned by get_ticket_field_definitions. |
| booleanValue | Exactly one | Value to store on a BOOLEAN field: true or false. |
| stringValue | Value to store on a STRING field, up to 255 characters. It also has to satisfy the definition's validation rule. | |
| singleValue | Value to store on a LIST_SINGLE_VALUED field: one label from the definition's availableValues. | |
| multiValue | Values to store on a LIST_MULTI_VALUED field: any number of labels from the definition's availableValues. | |
| postalAddress | Value to store on a POSTAL_ADDRESS field: an object with the keys street, district, city, state, postalCode and country. |
Returns
| Field | Description |
|---|---|
| fieldId | ID of the value that was created or already existed — the handle delete_ticket_field_value expects. |
| action | What the call did: created, updated or unchanged. |
Note: the value parameter must match the field's type, and archived definitions are rejected. If a ticket somehow holds more than one value for the same definition, the call fails and asks you to clean up with delete_ticket_field_value first.
Delete ticket field value (delete_ticket_field_value)
Removes one stored custom field value from a ticket. Works even when the underlying definition has been archived.
Parameters
| Parameter | Required | Description |
|---|---|---|
| fieldId | Yes | ID of the stored value, as returned by get_ticket_field_values. This is the value's own ID, not the definition ID. |
Returns
| Field | Description |
|---|---|
| fieldId | ID of the value that was deleted. |
Ticket write tools
Add note (add_note)
Adds an internal note to a ticket. Notes are visible to agents only, never to the customer.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
| text | Yes | Note body to store, as plain text. |
| reopenTicket | No | Reopen the ticket when it is already resolved. false by default, so a resolved ticket stays resolved. |
Returns
| Field | Description |
|---|---|
| noteId | ID of the created note. |
Note: attachments cannot be added through this tool.
Add tags (add_tags_to_ticket)
Applies one or more existing tags to a ticket.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
| tags | Yes | One or more tag IDs (4-character alphanumeric) or tag names, as returned by get_tags. Unknown tags are rejected — the tool does not create them. |
Returns: {"success": true}.
Remove tags (remove_tags_from_ticket)
Removes one or more tags from a ticket.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
| tags | Yes | One or more tag IDs or tag names to remove, in the same form add_tags_to_ticket accepts. |
Returns: {"success": true}.
Assign ticket (assign_ticket)
Assigns a ticket to an agent, or clears the assignment.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
| agentId | Yes | ID of the agent to assign the ticket to, as returned by list_agents. Must be present, but may be null to unassign. |
Returns: {"success": true}.
Transfer ticket (transfer_ticket)
Moves a ticket to a different department.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
| departmentId | Yes | ID of the department to move the ticket to, as returned by list_departments. |
| reopenTicket | No | Reopen the ticket after the transfer. false by default, so a resolved ticket stays resolved. |
Returns: {"success": true}.
Note: for an AI agent this is a final action — the agent's run finishes once the transfer succeeds.
Resolve ticket (resolve_ticket)
Marks a ticket as resolved.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
Returns: {"success": true}.
Note: for an AI agent this is a final action — the run finishes once the ticket is resolved. Add any tags or notes before calling it.
Reopen ticket (reopen_ticket)
Reopens a resolved ticket.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
Returns: {"success": true}, or the error Ticket is already open when there was nothing to reopen.
Mark as spam (mark_as_spam)
Marks a ticket as spam.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
Returns: {"success": true}, or {"note": "Ticket was already marked as spam"} when the ticket was already in that state.
Note: for an AI agent this is a final action — the run finishes here, so add any tags or notes first.
Mark as not spam (mark_as_not_spam)
Clears the spam mark and returns the ticket to the queue. Unlike mark_as_spam, this is not a final action.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d |
Returns: {"success": true}, or {"note": "Ticket was already not marked as spam"}.
Reply via WhatsApp (reply_via_whatsapp)
Sends a text reply to the customer on a WhatsApp ticket. This is the only MCP tool that writes a customer-visible message.
Requires the WhatsApp addon — on accounts without it the tool is neither offered nor callable.
Parameters
| Parameter | Required | Description |
|---|---|---|
| ticketId | Yes | Ticket identifier, e.g. 1a2b3c4d. Its channel must be whatsapp. |
| text | Yes | Reply text. WhatsApp enforces a maximum message length; an over-length reply is rejected with an error stating the limit. |
Returns
| Field | Description |
|---|---|
| messageId | ID of the reply that was queued for delivery. |
Conditions and caveats:
- The ticket's
channel(fromget_ticket_metadata) must bewhatsapp. Anything else is rejected. - The reply must fall inside the 24-hour WhatsApp customer service window — that is, within 24 hours of the customer's last message. Outside it, the call fails and the fallback is an approved WhatsApp template sent by a human agent, or an internal note.
- Text only — attachments are not supported.
- A successful result means the reply was stored and queued. Actual delivery to WhatsApp happens afterwards and its outcome is not reported by this tool.
- For AI agents the tool is locked to the ticket the run was started for; it cannot post to a different ticket found via
search_tickets.
Knowledge base tools
None of these tools assume a default knowledge base, so start with list_knowledge_bases and pass the knowledgeBaseId you get from it.
List knowledge bases (list_knowledge_bases)
Parameters: none.
Returns
| Field | Description |
|---|---|
| knowledgeBases[].id | Knowledge base identifier — this is what every other knowledge base tool expects as knowledgeBaseId. |
| knowledgeBases[].name | Knowledge base name. |
| knowledgeBases[].isActive | Denotes whether the knowledge base is switched on: true for an active one, false for a disabled one. |
List knowledge base categories (list_kb_categories)
Returns categories as a nested tree — the full subtree under a parent, or the whole knowledge base when no parent is given.
Parameters
| Parameter | Required | Description |
|---|---|---|
| knowledgeBaseId | Yes | ID of the knowledge base to read, as returned by list_knowledge_bases. |
| parentCategoryId | No | Root of the subtree to return. Omit (or pass 0) for the whole tree. |
Returns
| Field | Description |
|---|---|
| categories[].id | Category identifier — this is what the article tools expect as categoryId. |
| categories[].name | Category name. |
| categories[].parentCategoryId | Parent category ID (0 at root level). |
| categories[].visibility | Who can see the category: public or internal. |
| categories[].position | 0-based position among its siblings. |
| categories[].children[] | Nested child categories, same shape. |
| count | Total number of category nodes returned, children included. |
Search knowledge base articles (search_kb_articles)
Full-text search across a knowledge base — for finding an article that answers a customer's question, or checking whether one already exists.
Parameters
| Parameter | Required | Description |
|---|---|---|
| query | Yes | Return only articles whose title or content matches this keyword or phrase. |
| knowledgeBaseId | Yes | ID of the knowledge base to search, as returned by list_knowledge_bases. |
| categoryId | No | Return only articles in this category and its sub-categories, as returned by list_kb_categories. When omitted, the whole knowledge base is searched. |
| limit | No | Maximum number of articles to return, 10 by default, up to a maximum of 50. A higher value is quietly reduced to 50 rather than rejected. |
Returns
| Field | Description |
|---|---|
| articles[].id | Article identifier — this is what get_kb_article and update_kb_article expect as articleId. |
| articles[].title | Article title. |
| articles[].url | Public article URL. |
| articles[].summary | First ~300 characters of the article as plain text, truncated on a word boundary with an ellipsis. |
| articles[].description | The article's meta description, as shown in search engine results. |
| articles[].categoryId | ID of the category the article sits in. |
| articles[].knowledgeBaseId | ID of the knowledge base the article belongs to. |
| articles[].status | Publication state: published or draft. |
| articles[].visibility | Who can see the article: public or internal. |
Note: the full article body is not returned — fetch it with get_kb_article. There is no cursor or offset, so limit caps the result set at 50.
Get knowledge base article (get_kb_article)
Retrieves an article's full content, by ID or by the 6-digit code in its URL.
Parameters
| Parameter | Required | Description |
|---|---|---|
| articleId | One of the two | The article's numeric ID, as returned by search_kb_articles. |
| urlCode | One of the two | The 6-digit code in the article URL — for example 397021 in .../397021-article-title. |
Returns
| Field | Description |
|---|---|
| id | Article ID. |
| title | Article title. |
| url | Public article URL. |
| body | Full article body as HTML. |
| plainText | The same body content as plain text. |
| description | Meta description, as shown in search engine results. |
| keywords | Meta keywords set on the article. |
| categoryId | ID of the category the article sits in. |
| knowledgeBaseId | ID of the knowledge base the article belongs to. |
| status | Publication state: published or draft. |
| visibility | Who can see the article: public or internal. |
| position | 0-based position within its category. |
| createdAt | Datetime when the article was created, as an RFC 3339 timestamp, e.g. 2026-07-08T10:00:00+00:00. |
| changedAt | Datetime when the article was last changed, in the same RFC 3339 format. |
| attachments[] | Attachments of the article, each with id, fileName, contentType, size (bytes), isInline and downloadUrl. |
Note: as with ticket attachments, downloadUrl is single-use and expires after roughly 3 hours.
Create knowledge base article (create_kb_article)
Parameters
| Parameter | Required | Description |
|---|---|---|
| title | Yes | Article title (max 255 characters). |
| body | Yes | Article body in HTML. |
| categoryId | Yes | ID of the category to place the article in, as returned by list_kb_categories. |
| knowledgeBaseId | Yes | ID of the knowledge base to create the article in, as returned by list_knowledge_bases. |
| status | Yes | Publication state: published or draft. |
| visibility | Yes | Who can see the article: public or internal. |
| description | No | Meta description, shown in search engine results. |
| keywords | No | Meta keywords for SEO. |
| position | No | 0-based position within the category. Omit to append at the end. |
Returns
| Field | Description |
|---|---|
| articleId | ID of the article that was created — this is what get_kb_article and update_kb_article expect as articleId. |
| message | Confirmation text naming the article and its status. |
Note: attachments cannot be uploaded through this tool. Images referenced inline in the HTML body are picked up from the body itself.
Update knowledge base article (update_kb_article)
Changes an existing article. Only the fields you supply are changed; everything else keeps its current value.
Parameters
| Parameter | Required | Description |
|---|---|---|
| articleId | Yes | ID of the article to update, as returned by search_kb_articles. |
| title | No | New title (max 255 characters). |
| body | No | New body in HTML. |
| status | No | New publication state: published or draft. |
| visibility | No | New visibility: public or internal. |
| description | No | New meta description. |
| keywords | No | New meta keywords. |
| categoryId | No | ID of the category to move the article to, as returned by list_kb_categories. When omitted, the article stays where it is. |
| knowledgeBaseId | No | If supplied, must match the article's current knowledge base — moving an article between knowledge bases is not supported. |
| position | No | 0-based position within the category. |
Returns
| Field | Description |
|---|---|
| message | Confirmation text naming the updated article. |
Create knowledge base category (create_kb_category)
Parameters
| Parameter | Required | Description |
|---|---|---|
| name | Yes | Category name (max 255 characters). |
| knowledgeBaseId | Yes | ID of the knowledge base to create the category in, as returned by list_knowledge_bases. |
| visibility | Yes | Who can see the category: public or internal. |
| parentCategoryId | No | ID of the parent category, as returned by list_kb_categories. Omit for a root-level category. |
| keywords | No | Meta keywords for SEO. |
| position | No | 0-based position among siblings. |
Returns
| Field | Description |
|---|---|
| categoryId | ID of the category that was created — this is what the article tools expect as categoryId. |
| message | Confirmation text naming the created category. |
Update knowledge base category (update_kb_category)
Renames, moves, reorders or changes the visibility of a category. Only the fields you supply are changed.
Parameters
| Parameter | Required | Description |
|---|---|---|
| categoryId | Yes | ID of the category to update, as returned by list_kb_categories. |
| name | No | New name (max 255 characters). |
| visibility | No | New visibility: public or internal. |
| keywords | No | New meta keywords; pass an empty string to clear them. |
| parentCategoryId | No | Move the category under this parent, as returned by list_kb_categories; 0 moves it to root level. Moving a category under one of its own descendants is rejected. |
| knowledgeBaseId | No | If supplied, must match the category's current knowledge base. |
| position | No | 0-based position among siblings. |
Returns
| Field | Description |
|---|---|
| message | Confirmation text naming the updated category. |
Known limitations and gotchas
These are the boundaries people most often run into. Knowing them up front saves a lot of guessing when a prompt does not produce the result you expected.
Attachments
- File content is never inlined.
get_ticket_messagesandget_kb_articlereturn adownloadUrlper attachment instead. - Those links are single-use and expire in about 3 hours. Re-reading a link from an earlier response will usually fail — call the tool again to mint a fresh one.