Skip to main content
Connect an authorized MCP client to:
Use the existing MCP connection guide for setup. An OAuth grant exposes only authorized tools. A tool being absent can mean the grant lacks its scope. Existing grants are not widened automatically. The operation matrix lists all 18 Tickets, Escalation and Commerce tools and their scopes.

​
REST and MCP input mapping

MCP tools use the same domain services and response projections as REST: MCP JSON examples below are tool arguments, not JSON-RPC envelopes. The structured result contains statusCode and result; the ticket or list is under structuredContent.result. Do not confuse the transport wrapper with the domain object. The API Reference documents the underlying response schema.

​
Discover → inspect → assign → start → note → resolve → read back

1

Discover the entire relevant queue

Call list_tickets. Include Commerce explicitly and follow every remaining cursor with the same filters.
2

Inspect the exact item and supporting evidence

Call get_ticket with {"ticketId":"YOUR_TICKET_ID"} and list_ticket_events with the ID and limit. Check type, source, status, revision, assignee, permitted actions and context availability.Read the source conversation, stored messages, handoff policy, action receipts and delivery status with their existing tools and scopes. A knowledge gap’s source titles do not replace these reads. Purchase evidence requires commerce:sales:read. Report unavailable or denied context explicitly.
3

Select a human owner

Use list_assignable_operators to find an active team member. assign_ticket takes:
Use assign_escalation for an escalation. It also changes conversation ownership. The credential/grant remains the audit actor; it does not become the human assignee.
4

Start explicitly

Call start_ticket or start_escalation using the latest returned revision:
An agent cannot start an unassigned item. Reading, assignment and replying never imply Start work.
5

Record evidence and progress

Call add_ticket_note or add_escalation_note:
Notes are internal. Customer messages use separate sending tools with separate authorization.
6

Complete the correct workflow

For general manual work, call resolve_ticket once complete, or cancel_ticket when no longer needed. For human takeover, call resolve_escalation only after considering that AI may resume under the conversation’s remaining settings.
Commerce tickets require an authoritative purchase outcome. Use the Commerce tools; generic resolve/cancel cannot close them.
7

Read back

Call get_ticket again. Verify the exact ID, new revision, intended state and history. Check conversation policy or delivery evidence separately where needed. Revision numbers above illustrate a new item with no intervening writes; always use the actual result.

​
Create work or initiate a handoff

create_ticket requires a stored conversation, title and creation key:
create_escalation also requires a conversation and title, under conversations:handoffs:create. It immediately pauses AI through the canonical handoff path. It does not synthesize a guest message. Assign a human separately, then start work. update_ticket edits an open general ticket with ticketId and input containing current revision and at least one editable field. There is no escalation-title update tool or reopening tool in this version.

​
Retry discipline

  • On stale revision, reread and reconsider; do not increment the number locally or blindly replay.
  • On uncertain creation, retain the original key and exact input. Inspect a returned requestId using get_ticket_request_status before retrying.
  • Processing or reconciliation required does not establish success. Inspect any returned ticket ID and ownership; do not create a replacement handoff.
  • Use a new key for a genuinely new intent, not to get past an uncertain earlier attempt.
  • Commerce commands have their own sourceVersion, creation-style idempotency and read-back rules.
  • Revoked access stops reads, writes and authorized event delivery. Obtain a fresh explicit grant rather than impersonating a team member.
Built-in Agent approvals remain required for operations that use them. MCP visibility does not bypass approval or Commerce eligibility checks.