MCP tools reference

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 internal notes by default. Limited to 50 messages per call.

Available 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.

Response

Field	Description
messages[].id	Message identifier.
messages[].text	Message body as plain text.
messages[].author	`agent`, `customer`, `ai_agent`, `rule`, or `external_app`.
messages[].authorId	Identifier of the author.
messages[].type	`email`, `chat`, `whatsapp`, `instant_message`, `note` or `legacy_message`.
messages[].createdAt	Datetime when the message was added.
messages[].attachments[]	Attachments of the ticket messages, each with `id`, `fileName`, `contentType`, `size` (bytes) and `downloadUrl`.
nextCursor	Cursor referring to the last returned message, pass as `since` to retrieve next mesages. Returns `null` when there are no more messages.

Note: attachment content is never inlined in the result. downloadUrl is a short-lived, single-use link (valid roughly 3 hours, consumed by the first successful download), so fetch it once and keep the bytes.

Get ticket metadata (get_ticket_metadata)

Reads a ticket's properties: subject, status, originating channel, department, assignment, tags and timestamps.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket identifier, e.g. 1a2b3c4d

Returns

Field	Description
id	Internal ticket ID.
code	Human-readable ticket code.
subject	Ticket subject.
status	`init`, `new`, `open`, `answered`, `resolved`, `postponed`, `chatting`, `calling`, `closed`, `deleted` or `spam`.
channel	Channel the ticket came from: `email`, `contact_button`, `contact_form`, `invitation`, `call`, `call_button`, `facebook`, `facebook_message`, `twitter`, `forum`, `suggestion`, `instagram`, `instagram_mention`, `viber`, `whatsapp`, `telegram`.
departmentId	Department the ticket belongs to.
departmentName	Department name (archived departments included).
assignedAgentId	Assigned agent's ID; `null` when unassigned.
assignedAgentName	Assigned agent's display name. The agent's e-mail address is not returned — see Known limitations.
tags	Names of the tags currently on the ticket.
createdAt	When the ticket was created.
lastActivityAt	When the ticket last changed.

Note: this tool does not return customer/requester details, priority, or SLA data.

Get ticket summary (get_ticket_summary)

Returns the ticket's existing AI-generated summary and when it was produced.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket identifier, e.g. 1a2b3c4d

Returns

Field	Description
summary	Summary text as plain text. `null` when the ticket has no summary yet.
generatedAt	When the summary was generated; `null` together with `summary`.

Get ticket notes (get_ticket_notes)

Retrieves the internal notes on a ticket (agent notes, rule notes, API notes) with cursor-based pagination.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket identifier, e.g. 1a2b3c4d
since	No	Cursor from a previous response.

Returns

Field	Description
notes[].noteId	Note identifier.
notes[].text	Note text.
notes[].author.id	Author identifier.
notes[].author.name	Author display name.
notes[].author.type	`agent`, `ai_agent`, `rule` or `external_app`.
notes[].createdAt	When the note was added.
nextCursor	Pass as `since` to continue.

Get tags (get_tags)

Lists every tag defined in the account. This is the tag catalogue you pick from — it is not the list of tags on a particular ticket. For a ticket's own tags, use Get ticket metadata.

Parameters: none.

Returns

Field	Description
tags[].id	Tag ID (4-character alphanumeric).
tags[].name	Tag name.
tags[].isPublic	Whether the tag is visible outside the agent panel.

Search tickets (search_tickets)

Finds related or similar tickets. Results are ordered by last change, newest first.

Parameters

Parameter	Required	Description
status	No	Filter by status. Accepted: `new`, `open`, `answered`, `resolved`, `postponed`, `chatting`, `calling`. When omitted, deleted, closed and spam tickets are excluded and everything else is returned.
departmentId	No	Restrict to one department.
agentId	No	Restrict to tickets assigned to one agent.
query	No	Full-text search phrase.
limit	No	Maximum results; default 10, maximum 50 (higher values are capped).
cursor	No	Cursor from a previous response, to fetch the next page.

Returns

Field	Description
tickets[].id	Internal ticket ID — this is what other ticket tools expect.
tickets[].code	Human-readable ticket code.
tickets[].subject	Ticket subject.
tickets[].status	Current status (the full status list, including `closed`, `deleted`, `spam`, `init`).
tickets[].departmentId	Department the ticket belongs to.
tickets[].assignedAgentId	Assigned agent's ID.
totalCount	Total number of matching tickets, not just those on this page.
nextCursor	Pass as `cursor` for the next page.

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 no subject, department name or agent name is returned — only IDs.

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	Filter agents by name or e-mail address.

Returns

Field	Description
agents[].id	Agent ID.
agents[].name	Agent display name.
agents[].email	Agent e-mail address.

List departments (list_departments)

Lists the departments in the account, for routing and transfer decisions.

Parameters

Parameter	Required	Description
search	No	Filter departments by name.

Returns

Field	Description
departments[].id	Department ID.
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.
definitions[].code	Stable string code of the field.
definitions[].name	Field label.
definitions[].type	`BOOLEAN`, `STRING`, `POSTAL_ADDRESS`, `LIST_SINGLE_VALUED` or `LIST_MULTI_VALUED`.
definitions[].description	Field description.
definitions[].checkboxDescription	`BOOLEAN` fields only — the label next to the checkbox.
definitions[].validation	`STRING` fields 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":…}`.
definitions[].availableValues	`LIST_SINGLE_VALUED` and `LIST_MULTI_VALUED` fields only — the selectable option labels.

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 definition ID.
values[].code	Definition code.
values[].name	Field label.
values[].type	Field type, as in the definitions tool.
values[].value	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. Supply either this or `definitionCode` — never both, never neither.
definitionCode	One of the two	Definition code.
booleanValue	Exactly one	For `BOOLEAN` fields.
stringValue		For `STRING` fields (max 255 characters).
singleValue		Selected option label for `LIST_SINGLE_VALUED` fields.
multiValue		Selected option labels for `LIST_MULTI_VALUED` fields.
postalAddress		Keys `street`, `district`, `city`, `state`, `postalCode`, `country` for `POSTAL_ADDRESS` fields.

Returns

Field	Description
fieldId	ID of the created or existing value.
action	`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	The value's ID, as returned by `get_ticket_field_values`. Note this is not the definition ID.

Returns

Field	Description
fieldId	The deleted value's ID.

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 text.
reopenTicket	No	Reopen the ticket if it is resolved. Default `false`.

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	Tag IDs (4-character alphanumeric) or tag names. 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	Tag IDs or tag names to remove.

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	Agent to assign to. Must be present, but may be `null` to unassign. Resolve IDs with `list_agents`.

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	Target department. Resolve IDs with `list_departments`.
reopenTicket	No	Reopen the ticket after the transfer. Default `false`.

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	The WhatsApp ticket to reply to.
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 queued reply.

Conditions and caveats:

The ticket's channel (from get_ticket_metadata) must be whatsapp. 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.

AI assistant tools

These tools deliver an AI agent's output back into LiveAgent. They are meant for automated agent runs rather than interactive use, and each one finishes the run that called it.

Submit ticket summary (submit_ticket_summary)

Stores a generated summary on the ticket, where it appears in the agent panel.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket identifier, e.g. 1a2b3c4d
summary	Yes	The summary text.

Returns: {"success": true}.

Submit answer suggestion (submit_answer_suggestion)

Delivers a suggested reply for the ticket, which an agent can then review and send.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket identifier, e.g. 1a2b3c4d
text	Yes	The suggested reply text.

Returns: {"success": true}. Fails with submit_answer_suggestion requires an AI agent run when called outside an AI agent run — a personal MCP connection cannot use it.

Submit text modification (submit_text_modification)

Delivers generated or rewritten text as the answer-assistant result for a ticket.

Parameters

Parameter	Required	Description
ticketId	Yes	Ticket identifier, e.g. 1a2b3c4d
text	Yes	The generated or modified text.

Returns: {"success": true}. Like the tool above, it requires an AI agent run.

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	The value to pass as `knowledgeBaseId` to the other KB tools.
knowledgeBases[].name	Knowledge base name.
knowledgeBases[].isActive	Whether the knowledge base is active.

List KB 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	Knowledge base to read.
parentCategoryId	No	Root of the subtree to return. Omit (or pass `0`) for the whole tree.

Returns

Field	Description
categories[].id	Category ID.
categories[].name	Category name.
categories[].parentCategoryId	Parent category ID (`0` at root level).
categories[].visibility	`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 KB 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	Search keyword or phrase.
knowledgeBaseId	Yes	Knowledge base to search.
categoryId	No	Restrict to this category and its sub-categories.
limit	No	Maximum results; default 10, maximum 50.

Returns

Field	Description
articles[].id	Article ID.
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.
articles[].categoryId	Category the article sits in.
articles[].knowledgeBaseId	Knowledge base the article belongs to.
articles[].status	`published` or `draft`.
articles[].visibility	`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 KB 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.
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 content as plain text.
description	Meta description.
keywords	Meta keywords.
categoryId	Category ID.
knowledgeBaseId	Knowledge base ID.
status	`published` or `draft`.
visibility	`public` or `internal`.
position	0-based position within its category.
createdAt	When the article was created.
changedAt	When it was last changed.
attachments[]	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 KB article (create_kb_article)

Parameters

Parameter	Required	Description
title	Yes	Article title (max 255 characters).
body	Yes	Article body in HTML.
categoryId	Yes	Category to place the article in.
knowledgeBaseId	Yes	Target knowledge base.
status	Yes	`published` or `draft`.
visibility	Yes	`public` or `internal`.
description	No	Meta description for search results.
keywords	No	Meta keywords.
position	No	0-based position within the category. Omit to append at the end.

Returns

Field	Description
articleId	ID of the new article.
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 KB 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	Article to update.
title	No	New title (max 255 characters).
body	No	New body in HTML.
status	No	`published` or `draft`.
visibility	No	`public` or `internal`.
description	No	New meta description.
keywords	No	New meta keywords.
categoryId	No	Move the article to this category.
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.

Create KB category (create_kb_category)

Parameters

Parameter	Required	Description
name	Yes	Category name (max 255 characters).
knowledgeBaseId	Yes	Target knowledge base.
visibility	Yes	`public` or `internal`.
parentCategoryId	No	Parent category. 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 new category.
message	Confirmation text.

Update KB 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	Category to update.
name	No	New name (max 255 characters).
visibility	No	`public` or `internal`.
keywords	No	New meta keywords; pass an empty string to clear them.
parentCategoryId	No	Move under this parent; `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.

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_messages and get_kb_article return a downloadUrl per 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.

MCP tools reference

Ticket read tools

Get ticket messages (get_ticket_messages)

Get ticket metadata (get_ticket_metadata)

Get ticket summary (get_ticket_summary)

Get ticket notes (get_ticket_notes)

Get tags (get_tags)

Search tickets (search_tickets)

List agents (list_agents)

List departments (list_departments)

Ticket field tools

Get ticket field definitions (get_ticket_field_definitions)

Get ticket field values (get_ticket_field_values)

Set ticket field value (set_ticket_field_value)

Delete ticket field value (delete_ticket_field_value)

Ticket write tools

Add note (add_note)

Add tags (add_tags_to_ticket)

Remove tags (remove_tags_from_ticket)

Assign ticket (assign_ticket)

Transfer ticket (transfer_ticket)

Resolve ticket (resolve_ticket)

Reopen ticket (reopen_ticket)

Mark as spam (mark_as_spam)

Mark as not spam (mark_as_not_spam)

Reply via WhatsApp (reply_via_whatsapp)

AI assistant tools

Submit ticket summary (submit_ticket_summary)

Submit answer suggestion (submit_answer_suggestion)

Submit text modification (submit_text_modification)

Knowledge base tools

List knowledge bases (list_knowledge_bases)

List KB categories (list_kb_categories)

Search KB articles (search_kb_articles)

Get KB article (get_kb_article)

Create KB article (create_kb_article)

Update KB article (update_kb_article)

Create KB category (create_kb_category)

Update KB category (update_kb_category)

Known limitations and gotchas

Attachments

Related articles

Other Articles