> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage tickets with MCP

> Discover work, inspect evidence, select a human owner and safely reconcile every write.

Connect an authorized MCP client to:

```text theme={null}
https://platform-api.visitoai.com/m2m/v1/mcp
```

Use the existing [MCP connection guide](https://docs.visitoai.com/product-guides/getting-started/visito-mcp.md) 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](https://docs.visitoai.com/api-docs/tickets.md#routes-tools-and-permissions) 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:

| REST input | MCP argument |
| - | - |
| Path parameters such as `ticketId` or `saleId` | Top-level argument with the same name |
| Query parameters such as `includeCommerce`, `status`, `cursor` | Top-level argument with the same name |
| JSON request body | Object under `input` |
| `Idempotency-Key` header | Top-level `idempotencyKey` |

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.

```json theme={null}
{"includeCommerce":true,"status":"pending","owner":"unassigned","limit":25}
```

**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:

```json theme={null}
{"ticketId":"YOUR_TICKET_ID","input":{"revision":0,"operatorId":"YOUR_HUMAN_OPERATOR_ID"}}
```

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:

```json theme={null}
{"ticketId":"YOUR_TICKET_ID","input":{"revision":1}}
```

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`:

```json theme={null}
{"ticketId":"YOUR_TICKET_ID","input":{"revision":2,"note":"Front desk verified luggage storage until 6 pm. Reference: desk log DEMO-204."}}
```

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.

```json theme={null}
{"ticketId":"YOUR_TICKET_ID","input":{"revision":3,"note":"Verified the requested information and completed the work."}}
```

Commerce tickets require an authoritative purchase outcome. Use the [Commerce tools](https://docs.visitoai.com/api-docs/tickets/commerce.md); 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:

```json theme={null}
{"idempotencyKey":"luggage-storage-2026-10-16-01","input":{"conversationId":"YOUR_CONVERSATION_ID","title":"Confirm luggage storage after checkout","description":"Verify availability with the front desk."}}
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.