Async Jobs

Some MCP operations — today, only bulk_generate_access_codes — take longer than the 30-second budget a short-lived HTTP request can hold. Those tools return a job_id immediately and the client polls get_job_status for completion.

The pattern

1. The client invokes a long-running tool — for example bulk_generate_access_codes with a batch of several hundred codes.
2. The server enqueues the work and returns immediately:

{
  "data": {
    "job_id": "mjb_01HX...",
    "status": "queued",
    "enqueued_at": "2026-05-18T10:05:00Z"
  }
}

3. The client periodically calls get_job_status with the job_id:

{
  "data": {
    "job_id": "mjb_01HX...",
    "status": "completed",
    "result": {
      "count": 250,
      "batch_id": "btc_01HX..."
    }
  }
}

4. When status becomes completed or failed, the caller reads result or error accordingly.

Status values

Suggested polling cadence

• First 10 seconds: poll every second.
• Next 50 seconds: poll every 5 seconds.
• After 1 minute: poll every 30 seconds.

Jobs typically complete in well under a minute.

Persisting across sessions

Job IDs are stable. An agent that loses its conversation context can still poll get_job_status from a new session as long as the token owner matches — the job row is scoped to the token's team the same as any other read.

Which tools are async

Only bulk_generate_access_codes enqueues an async job today. Every other tool runs synchronously. The tool's description (surfaced at MCP handshake time) states whether the tool returns a job_id.

Related

• bulk_generate_access_codes — the tool that queues a job.
• get_job_status — the polling tool.
• preview_access_code_cost — call this first to see whether a batch will trigger overage billing before you queue it.