MCP worked examples

Connect the assistant using MCP setup. Start with pandrator_get_system_status and pandrator_get_capabilities. Inspect the live schemas: these examples describe the 0.13.0 contract, not fixed IDs that can be pasted unchanged.

Use a different idempotency key for each new logical request. When retrying the same request after an uncertain response, keep its key and exact arguments. Read the returned revision and handle instead of guessing the next number.

Native audiobook preparation

The example assumes an available speech provider and a UTF-8 text file inside an approved source root. Replace the capitalized placeholders with values returned by earlier calls.

pandrator_create_session(name="Short narration", idempotency_key="book-create-1")
pandrator_import_local_source(session_id=SESSION_ID, root="books", relative_path="excerpt.txt", expected_session_revision=SESSION_REVISION, idempotency_key="book-import-1")
pandrator_prepare_speech_plan(session_id=SESSION_ID, expected_revision=CURRENT_REVISION, source_artifact_id=SOURCE_ARTIFACT_ID, idempotency_key="book-plan-1")

Read the returned plan's blocks, voices, text and warnings. Resolve review issues before marking that exact revision reviewed. Do not mark an unread plan reviewed just to unlock generation.

pandrator_review_speech_plan(session_id=SESSION_ID, revision_id=PLAN_REVISION_ID, content_signature=INSPECTED_SIGNATURE, idempotency_key="book-review-1")
pandrator_generate_speech_plan(session_id=SESSION_ID, speech_plan_revision_id=PLAN_REVISION_ID, settings_source="current", idempotency_key="book-generate-1")
pandrator_get_generation_operation(operation_id=OPERATION_ID, wait_seconds=30)

Poll that same operation until it reaches a terminal state. Inspect its selected run and completed artifacts. Assemble the intended run, verify the export and use pandrator_download_artifact with its returned artifact ID. A service health response is not a generation result.

Correction performed by the assistant

A passive dispatch run lets the connected assistant perform bounded text work, rather than configuring another language-model provider in Pandrator. Create a correction run against a selected source, then claim a batch.

pandrator_create_dispatch_run(session_id=SESSION_ID, kind="correction", source_artifact_id=SOURCE_ARTIFACT_ID, idempotency_key="correct-create-1")
pandrator_claim_dispatch_batch(run_id=RUN_ID, idempotency_key="correct-claim-1")

Read the batch and change only what the task authorizes. Submit a typed result using the batch ID and its lease token; cue IDs come from that batch.

{"batch_id":"BATCH_ID","lease_token":"LEASE_TOKEN","idempotency_key":"correct-submit-1","result":{"kind":"correction","operations":[{"action":"edit","cue_ids":["CUE_ID"],"texts":["The reviewed correction."]}]}}

Pass that object to pandrator_submit_dispatch_batch. Supply either the typed result or the legacy response text, never both. Inspect pandrator_get_dispatch_run(run_id=RUN_ID) for remaining batches and the final artifact. Leases normally last 900 seconds and can be renewed or released. After expiration, claim again with a new claim key and use the new token; do not create a duplicate run.

If final artifact materialization failed after a submission, replay only the identical submission with its original idempotency key when the returned state allows it. A terminal failed run is not generally retryable. Follow the returned next actions and the passive-processing reference.

Files and permissions

The agent sees approved root names and relative paths, not permission to read arbitrary directories. ../ and paths outside the root are rejected. Audio-reference imports through MCP are limited to 16 MiB. Downloads go to the configured output root. Reading, configuration, execution and cancellation have separate scopes; Manager repair needs separate authority.