Operations

Some queries — especially large pagination or CSV export jobs — run as background operations. The Xpoz MCP server provides two tools for managing these: checkOperationStatus and cancelOperation.

How Operations Work

When a tool triggers a long-running task, it returns an operation ID instead of immediate results. Your agent then polls for completion using checkOperationStatus.

1. Agent calls a tool (e.g., large paging query)
   └── Server returns: operationId, status: "running"

2. Agent polls checkOperationStatus(operationId)
   └── Server returns: status: "running"

3. Agent polls again
   └── Server returns: status: "completed", results: [...]

Most AI agents handle this polling automatically. You typically don’t need to manage operations manually — just call a tool and your agent retrieves the results when ready.

Operation States

State	Description
`running`	Operation is actively executing
`completed`	Successfully finished — results are available
`failed`	An error occurred during execution
`cancelled`	Gracefully stopped by a `cancelOperation` call

checkOperationStatus

Polls the status of an async operation and retrieves results when complete.

Parameter	Type	Required	Description
`operationId`	string	Yes	The operation ID returned by the initiating tool call

What it returns by state:

completed
running
failed

Returns the operation results:

For query operations: Paginated results with data
For CSV export operations: An S3 download URL

{
  "status": "completed",
  "message": "Operation completed successfully. Processed 487 items.",
  "results": [...]
}

Returns the current status with elapsed time:

{
  "status": "running",
  "message": "Processing... 250 processed",
  "duration": 12
}

Returns the error details:

{
  "status": "failed",
  "message": "Operation failed: Connection timeout"
}

cancelOperation

Gracefully stops a running operation.

Parameter	Type	Required	Description
`operationId`	string	Yes	The operation ID to cancel

Only works on operations with running status. The operation stops at its next processing checkpoint.

If you receive an error that an operation was not found, it may have expired. Re-issue the original query to start a new operation.

Response Modes — CSV mode triggers async operations for large exports
Pagination — Paging mode may trigger operations for large result sets

MCP Server

MCP Tools

How Operations Work

Operation States

checkOperationStatus

cancelOperation

​How Operations Work

​Operation States

​checkOperationStatus

​cancelOperation

​Related

How Operations Work

Operation States

checkOperationStatus

cancelOperation

Related