Pandrator MCP

Pandrator MCP connects your AI assistant to Pandrator. The assistant can inspect projects, help process text and media, and carry out the actions you authorize. It can work with Pandrator on the same computer or on a configured remote host.

For a local installation, Manager runs an authenticated Streamable HTTP service on loopback. Stdio is also available for remote targets and hosts that start a separate MCP process for each connection.

The sidecar talks only to Pandrator's versioned HTTP APIs. It does not import the application ORM or job queue, accept model-selected URLs, expose arbitrary files or commands, or store credentials in MCP arguments and results.

For public workflow concepts, start with passive dispatch, remote and headless operation, and privacy and security. This guide covers MCP installation, target configuration, permissions, enrollment, troubleshooting and protocol support.

Optional workflow skill

The repository includes the portable pandrator-workflows skill, with guidance for quick transcription, passive document/subtitle/speech processing, recording edits, generation, recovery, and verified output delivery.

Copy the whole skills/pandrator-workflows directory, including its references folder, into your MCP host's skill directory. For Codex, the usual destination is ~/.codex/skills/pandrator-workflows; use your configured location if different. Reload the host's skills as needed. Other hosts should use their documented SKILL.md installation mechanism.

The skill does not install or authorize the MCP connection. Complete the host connection setup below first; an agent can also use the MCP's packaged guides without installing this optional skill.

The folder is bundled in MCP 0.4.1 and newer. To locate it in an installed package, run this with the Python interpreter from the environment containing pandrator-mcp:

python -c "from importlib.resources import files; print(files('pandrator_mcp') / 'skills' / 'pandrator-workflows')"

Installing or upgrading the MCP package does not automatically install or update skills in your host.

What agents can do

The current tool surface supports:

• packaged, versioned explanations of Pandrator and its workflows;
• target, capability, session, workflow, source, artifact, provider, voice, durable-work, and redacted-event inspection;
• safe browsing of operator-approved local roots, resumable source import, and verified artifact download without putting file bytes in model context;
• session creation and revision-safe session, source, and settings changes;
• catalog-backed TTS service, model, and voice selection plus typed export variants and generation-run selection;
• one-turn model-orchestrated workflow procedures that sequence passive stages before creating the immutable native workflow plan;
• live media-edit procedures that attach recordings or Zoom captions, select CTC/ASR timing, drive passive cut proposals through review, render, and optionally materialize the result;
• filtered parameter-definition discovery for exact setting names, sections, and workflow kinds;
• immutable workflow planning followed by explicit execution;
• passive subtitle correction/translation, PDF/EPUB source-cleaning, and speech-text optimization runs with serial or supported bounded-parallel dispatch, short-lived leases, and typed submissions;
• durable-work cancellation;
• Manager status and diagnostics;
• immutable Manager component plans, runtime control, and plan execution; and
• local-managed and separately enrolled HTTPS recovery access when Pandrator itself is unavailable.

Complex actions stay in Pandrator. An agent first obtains a native immutable plan, presents its effects and confirmation requirements, and then executes that exact plan. Use an idempotency key where the operation supports one. For an unkeyed write, such as pronunciation creation, inspect current state before retrying an uncertain response. Concurrent changes produce an explicit revision or stale-plan error instead of a silent overwrite.

TTS discovery distinguishes a service's advertised model roster from the static package catalogue. audio.cpp model_states includes listed, loaded, and selectability_reason; selectable is null when an advertised model's service health is unknown. A package listed by Manager does not by itself establish service readiness or a prepared voice reference. Compare exact service and model IDs before changing a project's configuration.

Model-orchestrated workflow procedures

pandrator_plan_orchestrated_workflow is the single-turn intent/procedure layer above the existing immutable native plan. It reads the live session and workflow, returns canonical correction → translation → speech-optimization passive phases, and names each create/claim/submit loop. The first next_action starts the requested passive stage; after those artifacts are complete, the procedure points to pandrator_plan_workflow, whose exact plan must still be reviewed and executed. The procedural result is not an immutable execution snapshot because passive artifacts change the native workflow state fingerprint.

The procedure can carry typed export options and an optional local materialize step. A supplied filename strictly requires materialize=true; filenames must be plain names without path separators, NUL, . or ... Materialization lists current export artifacts before downloading the selected artifact. These delivery controls stay outside the native output overrides; only the typed export settings are merged into that final plan. Passive create arguments inherit each section's live effective settings and then apply the matching safe procedure override. Each generated passive idempotency key is the deterministic procedure retry identity for that live revision, goal, and resolved packet; changed inputs or revisions produce a new key.

Passive stages default to serial delegation. Set execution_mode=parallel with max_parallel_batches from 2 through 8 to expose one bounded wave to separate workers at a time. Every worker in a wave receives the same typed context capsule; workers return bounded context deltas, which are merged in batch order before the next wave. A parent model can populate the initial capsule itself or delegate that extraction first. Serial mode additionally hands accepted boundary output to the next worker.

pandrator_get_work accepts an optional bounded wait_seconds (up to one hour). It polls according to the application's poll_after_ms hint, clamped to a safe 250 ms–10 s interval, and returns wait telemetry. A host's own MCP request or gateway timeout can still end the call before this application-side wait expires, so clients should preserve the returned work handle and follow the generated next_action when necessary.

pandrator_describe_parameters is the filtered parameter-discovery surface. Provide at least one section, name, workflow kind, or query filter; the sidecar does not permit an indiscriminate definitions dump. Definitions are passed through from the application's safe {section, name, label, description, default, value_type, unit, minimum, maximum, choices, applicability, caveat} contract.

For document workflows, the public document-ingestion reference explains PDF layout/OCR, EPUB structure, deterministic and optional model-assisted cleanup, artifacts, and narration preparation. MCP plans and monitors those native stages; it does not parse books in the sidecar. Source cleaning can use Pandrator's configured provider or the passive dispatcher, where the MCP host model performs editorial review and Pandrator retains parsing, validation, and artifact ownership.

Subtitle dispatch

Dispatch is a passive pull loop for correction and translation. Create a run, then claim one batch at a time. Only the claim response discloses that batch's canonical task, actionable batch.cues, bounded boundary context, and short-lived lease_token; list/get calls return metadata only. Cue text occurs once. Timing is nested once per actionable cue in full mode, limited to positive overlap in overlap_only, and absent in none mode. Stable source-revision cue_id values are used for submission; batch_ordinal is presentation only. Claim reports run_status and batch_status separately so replaying a completed claim cannot masquerade as a completed run. An explicit translation artifact may also be the source of a correction run; the returned output_role: translation preserves its language and downstream track semantics while a new translation revision is materialized.

Submit a typed result: correction uses kind: correction plus operations over cue_ids; translation uses kind: translation, one item per cue_id, and optional glossary_updates. response_text remains only as a compatibility path for raw model adapters. Accepted batches are followed by the next sequential claim. If validation rejects a result, repair and resubmit it while the lease remains valid. Renew slow work or release abandoned work. The final accepted batch automatically finalizes the run; retry the same final submission and idempotency key if transient materialization leaves it finalizing.

Media-edit orchestration

For a media_edit session, pandrator_plan_media_edit_workflow inspects live source, workflow, timing, edit-revision, passive-dispatch, render, and artifact state and returns exactly one safe next action. Call it again after every action; it is a read-only procedure planner, not an atomic execution snapshot. Create the session first with workflow_kind=media_edit; the model can then provide approved recording and transcript source references to the planner.

transcript_mode=auto prefers an attached transcript and otherwise uses a generated ASR transcript. Local source imports and reusable-source attachment accept role=transcript, so Zoom SRT/VTT captions can be attached through MCP without treating them as primary media. Caption mode can configure bounded CTC, CTC-with-ASR-fallback, or ASR lexical alignment, while stt_overrides selects the normal ASR/VAD settings. The default managed Canary CTC aligner does not load a whole-recording ASR model. Source files remain limited to operator-approved named roots.

The model-hosted passive dispatcher proposes whole-recording cuts. Its result is always an unreviewed edit revision: list bounded cuts with pandrator_list_media_edit_cuts, inspect relevant boundaries, and refine one edge at a time with pandrator_refine_media_edit_boundary before re-planning and approving. Rendering remains blocked until that revision is explicitly reviewed. Optional materialization downloads the sole current render, or lists candidates when selection is ambiguous.

PDF and EPUB source-cleaning dispatch

For an attached PDF or EPUB, call pandrator_create_source_cleaning_dispatch_run. Preparation is asynchronous because local PDF extraction may include OCR. Inspect the run until it is ready, then claim and submit six sequential phases with the corresponding source-cleaning tools.

A claim discloses only that phase's document summary, bounded evidence, candidate blocks, server proposals, and operation allowlist. Decide every proposal with accept or reject; optionally add phase-appropriate typed operations over disclosed block IDs. Do not return rewritten book text.

The claim's candidates are a starting point, not a heuristic gate. While the lease is active, use pandrator_inspect_source_cleaning_dispatch_extraction to browse, search, inspect context or structure, preview selectors, and batch independent lookups. Use view: working for the result of accepted earlier phases and view: baseline for the original deterministic extraction. EPUB runs also offer a read-only view: source over the structured publisher markup, so a host model can investigate doubtful omissions, links, IDs, and formatting. Working/baseline IDs returned by inspection are added to the batch's audited valid scope; source-only IDs are reported separately and can never be mutation targets. The final text_repair phase permits targeted replace_block corrections for confirmed extraction defects.

Footnote inspection returns structurally supported candidates by default. Plain numbered lines are deliberately withheld because captions, lists, and numbered prose are common; request include_ambiguous: true to inspect those low-confidence lines when the edition warrants a broader search.

There is no provider, model-token, or iteration budget in this passive path. evidence_limit is only a per-phase transport bound: default 500, range 20–2,000. MCP application responses permit 8 MiB by default with a 16 MiB safety ceiling. After the last phase, Pandrator applies and validates the accepted operations and selects the resulting clean_text artifact. Normal workflow planning can then continue with narration preparation.

The source must already be managed and attached. Use pandrator_import_local_source for a file beneath an operator-approved named root, or attach a source returned by pandrator_list_sources. The cleanup tools themselves never accept an arbitrary filesystem path.

Speech-optimization dispatch

After narration preparation or subtitle translation/correction, call pandrator_create_speech_optimization_dispatch_run to let the MCP host model prepare text for speech without a Pandrator LLM provider. Sources are managed SRT, prepared-narration JSON, or TXT artifacts; PDF/EPUB and media inputs must first pass through extraction or transcription.

Claim batches sequentially. The claim's batch.units are the only actionable items and carry stable unit_id values, language, optional speaker, and, when requested, one timing object per SRT unit. Boundary context is read-only and never repeats timing. Submit kind: speech_optimization with every unit_id exactly once, in order, leaving text unchanged when no improvement is needed.

char_limit and max_units_per_batch are transport bounds rather than model budgets. Defaults are 20,000 characters and 100 units; supported maxima are 1,000,000 and 500. Pandrator neither chooses nor calls a model, and the host may subdivide a claimed batch internally. The final accepted batch materializes a normal tts_optimized artifact, pinned against source, selection, and output changes. Finish this stage before starting speech generation.

Guidance remains available even when no target can be reached.

MCP protocol compatibility

The current sidecar pins the official Python SDK 2.2.0 and supports the final MCP 2026-07-28 specification. Modern hosts connect through server/discover and attach the negotiated protocol metadata to requests; maintained older hosts can still use the legacy initialize handshake. The same server therefore works with current clients without abruptly abandoning existing integrations.

Tools expose JSON Schema inputs, annotations, structured JSON results, and a text JSON fallback. Tool, resource, and prompt discovery are deterministic. Expected business failures are returned as normal MCP tool results with isError: true and a typed Pandrator error object in the text. Modern list results include private-cache hints and every ordinary result carries the required resultType through the SDK.

Managed HTTP follows the final stateless request model at /mcp, binds only to a loopback IP, validates Host and Origin, caps request bodies at 16 MiB, and requires a separate pre-provisioned bearer on every protocol request. The Manager probes its unauthenticated, non-sensitive /health identity endpoint. The HTTP bearer is not an application or Manager token.

For stdio, stdout is reserved exclusively for newline-delimited MCP frames; dependency diagnostics from both tool and resource handlers are redirected to stderr. Protocol discovery, structured-content fallback, modern stdio, legacy negotiation, annotations, and stdout-noise containment are covered by the contract tests.

The server deliberately does not advertise deprecated protocol Roots, Sampling, or Logging capabilities. Its named local roots are ordinary sidecar configuration, not the deprecated MCP Roots feature. Pandrator's durable work and passive dispatch handles remain explicit tool arguments rather than using the optional Tasks extension; this keeps long-running application state usable by both modern and maintained legacy hosts.

Install

Use the MCP and application packages from the same Pandrator release. Keep the adapter and application versions compatible. An older application may not provide routes required by newer tools. After upgrading, restart or reconnect your MCP client so it loads the current tool schemas. With Python 3.11 or 3.12, install it as an isolated command-line tool:

pipx install "pandrator-mcp[credential-stores,manager]"
# or
uv tool install "pandrator-mcp[credential-stores,manager]"

For development from the repository root:

python -m pip install -e "./pandrator_mcp[credential-stores,manager]"

The credential-stores extra is required for target login, which saves tokens in Windows Credential Manager, macOS Keychain, or Linux Secret Service. The keychain must be available and unlocked for your user. --headless changes the browser approval flow; it does not remove this storage requirement.

The manager extra supports local Manager discovery. You can omit it for a sidecar that connects only to external targets.

Choose a transport

Managed local HTTP

When the active application runtime includes Pandrator's automation extra, the Manager registers optional service pandrator.mcp. Starting Pandrator starts the core API and worker, then the HTTP MCP. An MCP startup failure is reported in GET /v1/application, GET /v1/services, and the service log, but does not stop the browser application.

The endpoint is http://127.0.0.1:8099/mcp. The Manager creates a distinct owner-protected credential at <workspace>/Pandrator/state/mcp.secret and a non-secret target file at <workspace>/Pandrator/state/mcp-targets.json. The managed target is named managed-local.

Generate a host fragment only in a private local terminal. The acknowledgement flag is required because the fragment contains the HTTP bearer:

pandrator-manager --workspace /path/to/parent mcp-config codex --include-credential
pandrator-manager --workspace /path/to/parent mcp-config claude-code --include-credential
pandrator-manager --workspace /path/to/parent mcp-config opencode --include-credential
pandrator-manager --workspace /path/to/parent mcp-config antigravity --include-credential

Merge it into the host's private user configuration. Do not commit it or paste it into a prompt. In a development or custom installation without the Manager wrapper, invoke pandrator-mcp managed-host-config directly with the same host, workspace, and acknowledgement flag. The public agent-connection guide explains the transport choice and local-root configuration.

Stdio

For an explicit stdio target backed by a local Manager installation, use the same parent directory chosen during installation. For example, in Windows PowerShell, if the managed installation is C:\Applications\Pandrator:

pandrator-mcp target add local --mode local --workspace C:\Applications
pandrator-mcp target pin local
pandrator-mcp doctor --target local
pandrator-mcp stdio --target local

On Linux, an installation at /srv/Pandrator uses --workspace /srv instead. Use an absolute parent path; supplying the inner Pandrator directory makes discovery look for another Pandrator directory inside it. A process is bound to one named target at startup; tools cannot switch its destination.

Target configuration

The default non-secret target file is:

• %APPDATA%\Pandrator\mcp-targets.json on Windows; or
• $XDG_CONFIG_HOME/pandrator/mcp-targets.json on Linux/macOS, falling back to ~/.config/pandrator/mcp-targets.json when XDG_CONFIG_HOME is unset.

Use PANDRATOR_MCP_CONFIG to select another file for the process. For target commands, place the option before the subcommand: pandrator-mcp target --config PATH add NAME .... Other commands own their own option, for example pandrator-mcp print-config --config PATH. pandrator-mcp print-config prints a public projection without credential references.

Approved local files and outputs

The operator chooses which sidecar-host directories are visible. Expose each source directory under an opaque name and configure one output directory:

pandrator-mcp target source-root-add local downloads /home/me/Downloads
pandrator-mcp target source-root-add local library /srv/media/library
pandrator-mcp target output-root-set local /home/me/Pandrator-outputs
pandrator-mcp target source-root-list local

For managed HTTP, new installations expose the current user's home directory under the opaque root name home and use <workspace>/exports for downloaded artifacts by default. The application Settings page can add, remove, or replace approved roots.

For managed HTTP, use target managed-local and pass the managed target file when administering paths from the lower-level CLI:

pandrator-mcp target --config /path/to/parent/Pandrator/state/mcp-targets.json \
  source-root-add managed-local downloads /home/me/Downloads
pandrator-mcp target --config /path/to/parent/Pandrator/state/mcp-targets.json \
  output-root-set managed-local /home/me/Pandrator-outputs

Managed MCP path changes are reloaded on the next local browse/import/download operation, so restarting Pandrator is not required.

Use Windows absolute paths when the adapter runs on Windows. The MCP model sees root names and relative entries, never these absolute paths. Symlinks are not offered for import, and the importer opens every path component without following symlinks.

pandrator_browse_local_sources lists approved entries. pandrator_import_local_source hashes the selected regular file, reuses an identical managed source when possible, otherwise uploads it in resumable chunks, and then attaches it with the inspected session revision. Upload state and completion results are replayable, so an interrupted model turn can safely continue.

For text already present in the conversation, pandrator_create_text_source creates and attaches a bounded UTF-8 source directly. This avoids manufacturing a temporary local file solely to feed short narration or audiobook text into a session.

“Local” means local to the MCP process: the Manager-owned service for managed HTTP, or the agent-host process for stdio. Pandrator itself may be on the same computer or at a fixed remote target. For a remote target the stdio process streams bytes directly over the authenticated Pandrator API; the bytes are never encoded into an MCP tool result or model prompt.

pandrator_download_artifact performs the reverse operation. It streams one immutable artifact into the approved output root, resumes a partial transfer with HTTP Range, verifies size and SHA-256 metadata, and atomically publishes the completed file. It never returns the remote server's storage path.

End-to-end agent workflow

For a request such as “take the course video in Downloads, transcribe it, correct and translate the subtitles, generate a voiceover, and give me two final variants,” the intended sequence is:

1. call pandrator_recommend_next_steps, target status, and the matching guide;
2. browse an approved root, create or inspect a session, and import the source;
3. plan and execute transcription, then poll the returned work to terminal;
4. run passive correction and translation sequentially, with the host model producing and submitting each batch itself;
5. optionally run passive speech optimization before generation;
6. resolve live TTS choices with pandrator_get_tts_catalog, inspect the TTS settings revision, and apply exact IDs with pandrator_configure_tts;
7. plan and execute generation, poll it to terminal, and inspect generation runs;
8. create and execute one pandrator_plan_export_variant per requested output; export variants run directly from the selected completed generation run and assemble that run first only when the requested audio mode requires it; then
9. list the resulting artifacts and download each requested deliverable.

Service, model, and voice names mentioned by a user are preferences or examples. The agent must match them against the live catalog and ask for a choice only when the requested option is absent or ambiguous. Upload chunking, download resumption, and retry transport details are automatic rather than model-facing knobs.

Collaboration and per-person enrollment

Pandrator starts in Solo. An Administrator sets the initial Administrator password and enables collaboration; existing private projects are not shared. Use the collaboration guide or call pandrator_explain_system(topic="collaboration", detail="full") for the complete account/workspace workflow. Workspace Members can edit/process/export ordinary shared content; workspace Managers additionally manage membership. Instance Administrators manage users and missing-model acquisition. These roles are separate.

Each teammate runs a personal stdio sidecar, enrolls with browser PKCE as their own named account, and explicitly approves the relevant workspaces or view-only projects. Never share the managed local HTTP bearer or use an Owner bootstrap profile as a teammate identity. The scope recipes below apply alongside current role, membership and resource approval.

For example, on a workstation connecting to an already configured HTTPS server:

pandrator-mcp target add team --mode external --origin https://pandrator.example --scope app.read --scope app.write --scope app.workspaces.enroll --scope app.run
pandrator-mcp target login team
pandrator-mcp target pin team
pandrator-mcp doctor --target team
pandrator-mcp stdio --target team

Sign in as the intended teammate in the approval browser. To request additional scopes later, use target login team --scope ... with the complete desired set, including scopes still needed, then review the new browser approval. Use pandrator_get_target_status to inspect granted and missing requested scopes; it currently does not display the account's name/instance role. Check that in the enrollment browser.

Use pandrator_list_workspaces and explicitly supply workspace_id on creation tools that advertise it. There is no persistent MCP workspace selection, list_sessions workspace filter or folder tool. Organize folders in the browser. Copy existing private projects through preview/current-copy tools, supplying any required destination connections. A copy is independent and starts Unfiled; private credentials and personal folders do not become shared.

Scope recipes

Request only the authority the agent needs:

app.credentials.read and app.credentials.write exist in the application authorization model, but the MCP does not expose credential values or general credential-setting tools.

Direct app-down recovery is a different audience. Its possible scopes are manager.read, manager.runtime, and manager.mutate, and it requires a separate enrollment.

External HTTPS server

This is the recommended remote topology: the agent host runs the local stdio sidecar and the sidecar connects to a fixed Pandrator HTTPS origin.

pandrator-mcp target add production ^
  --mode external ^
  --origin https://pandrator.example ^
  --scope app.read ^
  --scope app.write ^
  --scope app.run ^
  --scope app.cancel ^
  --scope manager.read

pandrator-mcp target login production
pandrator-mcp target pin production
pandrator-mcp doctor --target production

Use \ instead of ^ for POSIX shell line continuation. target login opens an out-of-band account-consent page, uses S256 PKCE, and writes the issued token directly to the OS credential store. --headless provides the copy/paste TTY flow, while --no-open-browser prints the authorization URL. Tokens are never accepted on the command line.

An identity pin captures the stable application instance ID and canonical origin. A changed identity fails closed. Only use target pin --replace-identity after independently verifying an intentional rebuild.

Home, LAN, or VPN

Prefer HTTPS or a VPN. For a private certificate authority:

pandrator-mcp target add home ^
  --mode lan ^
  --origin https://pandrator.home.arpa ^
  --allowed-cidr 192.168.10.0/24 ^
  --ca-bundle C:\certificates\home-ca.pem ^
  --scope app.read ^
  --scope app.write ^
  --scope app.run ^
  --scope app.cancel

pandrator-mcp target login home
pandrator-mcp target pin home
pandrator-mcp doctor --target home

Every DNS result must remain inside an explicitly configured private CIDR. Link-local and cloud-metadata destinations remain forbidden. Deliberately accepted private HTTP additionally requires --allow-insecure-http; it is not available for Internet targets or direct Manager recovery.

Application without Pandrator Manager

Use --mode external-application when an external deployment intentionally has no Manager:

pandrator-mcp target add hosted-app ^
  --mode external-application ^
  --origin https://pandrator.example ^
  --scope app.read ^
  --scope app.write

Application tools continue to work. Manager tools return the typed manager_unavailable result instead of inventing a control plane.

Optional app-down Manager recovery

Normal Manager calls go through Pandrator's same-origin, bounded Manager proxy. The Manager's permanent local bearer stays on the target host.

For recovery while Pandrator is stopped, prepare a distinct HTTPS Manager origin and add it to the target:

pandrator-mcp target configure-recovery production ^
  --origin https://recovery.pandrator.example ^
  --recovery-scope manager.read ^
  --recovery-scope manager.runtime

pandrator-mcp target login production --manager-recovery
pandrator-mcp doctor --target production

configure-recovery preserves the application origin, scopes, enrollment, and identity. By default it also reuses the target's non-secret automation client ID for attribution across the two audiences. It refuses to overwrite an already enrolled recovery credential; revoke that client before changing its recovery identity.

Recovery enrollment requires an already authorized Manager recovery browser. The approval page shows the client, application and recovery identities, requested scopes, and expiry. The resulting credential:

• is accepted only by that Manager recovery audience;
• is bound to the application origin and both instance identities;
• expires after at most 30 days;
• is rate-limited per automation client;
• cannot access network settings, arbitrary files, or the permanent bearer; and
• is audited with client, request, and trace identifiers.

Availability failures may fall back from the application proxy to enrolled recovery. Authorization, scope, identity, and policy failures never do.

Remote Manager mutations through the application proxy also require the operator to set PANDRATOR_ALLOW_REMOTE_MANAGER_MUTATIONS=1 on that deployment. Calls still require current instance Administrator authority and the relevant Manager scopes; workspace management rights are insufficient. Possessing an application or recovery token does not enable that server-side policy.

Preparing a home server or pod

The Manager's documented remote launcher prepares the two canonical origins:

pandrator-manager-launcher setup ^
  --workspace /srv/pandrator ^
  --remote-setup-url https://recovery.pandrator.example ^
  --remote-pandrator-url https://pandrator.example ^
  --trusted-proxy-hops 1 ^
  --no-open

For an ingress in another pod or network namespace, also pass --network-bind-host 0.0.0.0 and restrict that listener with platform network policy. A production deployment should:

1. assign stable DNS names and valid HTTPS certificates;
2. persist the Pandrator data root and Manager workspace/state;
3. configure the exact public origins and trusted proxy-hop count;
4. expose only Pandrator and, if needed, the bounded recovery origin;
5. keep the permanent Manager client endpoint local;
6. put deployment secrets in the platform secret store;
7. enroll and pin from the workstation running the agent host; and
8. pass doctor before enabling writes.

Standalone application

For a Python installation without Manager, follow the public-hosting guide. It covers password initialization, the web process, the separate worker and using one persistent data directory for all three. Use HTTPS or a VPN for access from another computer. The MCP target should use --mode external-application when Manager is absent.

Losing the application or Manager state volume changes its stable identity. The MCP rejects the replacement until the owner verifies and deliberately re-enrolls it.

Codex, Antigravity, OpenCode, or Claude Code can help prepare a pod, service unit, reverse proxy, TLS ingress, persistent volumes, and firewall rules. A useful request is:

Help me prepare a single-owner Pandrator pod on <platform>.
Use https://pandrator.example for the application and
https://recovery.pandrator.example for optional recovery. Follow the
Pandrator MCP remote-target guide, persist application and Manager state,
restrict ingress, and put credentials only in the platform secret store.
Generate reviewable infrastructure code and validation commands. Stop before
deploying or exposing the service, show me the proposed network surface, and
ask for approval.

Review generated infrastructure as carefully as application code. The agent can accelerate setup, but the operator still owns DNS, certificate, firewall, volume, and exposure decisions.

Configure a stdio MCP host

Generate a secret-free local-stdio fragment after the target exists:

pandrator-mcp host-config codex --target production
pandrator-mcp host-config claude-code --target production
pandrator-mcp host-config opencode --target production
pandrator-mcp host-config antigravity --target production

The generated command is always:

pandrator-mcp stdio --target production --config <absolute-target-file>

Use --executable ABSOLUTE_PATH if the host does not inherit the shell's PATH, and --server-name NAME to change the host-visible name.

Merge the fragment into an existing host file rather than overwriting unrelated servers. Give each Pandrator target a separate entry. Never add an origin, token, proxy, certificate path, or credential reference to model- visible tool arguments.

The generated fragments contain commands and non-secret file paths, never tokens. You need to configure only the agent host you actually use.

For Codex, either merge the generated TOML or register the exact stdio command:

codex mcp add pandrator-production -- pandrator-mcp stdio --target production --config /absolute/path/to/mcp-targets.json
codex mcp get pandrator-production

The generated Codex fragment uses default_tools_approval_mode = "writes". Interactive writes therefore remain reviewable. A non-interactive codex exec run rejects an approval-requiring write unless the operator explicitly selects an appropriate approval policy for that already reviewed action.

For managed local HTTP, use pandrator-manager mcp-config from Choose a transport. Unlike these stdio fragments, that output necessarily contains the dedicated HTTP bearer and belongs only in a private user configuration.

Diagnostics and lifecycle

Run these before giving an agent write authority:

pandrator-mcp target list
pandrator-mcp target test production
pandrator-mcp doctor --target production
pandrator-mcp print-config

doctor checks profile validation, DNS/network policy, TLS, API compatibility, authentication, pinned identity, Manager and recovery state, and capabilities. It never prints a token or credential reference.

Server-side revocation and local removal are distinct:

• rotate an application credential by running target login NAME again; the same client ID is retained, the old server token is revoked, and the native keyring value is replaced;
• list and revoke application clients on the target host with pandrator --data-dir DATA --json auth automation-client list and pandrator --data-dir DATA --json auth automation-client revoke CLIENT_ID --yes;
• list and revoke recovery clients as the local Manager owner with pandrator-manager --workspace WORKSPACE automation-client list and pandrator-manager --workspace WORKSPACE automation-client revoke CLIENT_ID --yes;
• delete the workstation keyring credential with pandrator-mcp target logout NAME --yes (add --manager-recovery for that separate audience); then
• remove the non-secret profile with pandrator-mcp target remove NAME --yes.

Removing a target does not delete remote Pandrator data and is not a substitute for server-side credential revocation. If a profile still references credentials, removal refuses to guess: choose --delete-local-credentials or --keep-local-credentials explicitly. Both options still leave server-side revocation to the owner commands above. Changing a credential-store reference during re-login is also refused until logout, preventing an old native secret from becoming an invisible orphan.

Security boundaries

• The sidecar connects only to the fixed target saved in its local profile; tools cannot supply a different destination.
• Tokens are resolved from the credential store and are never accepted in MCP arguments.
• Managed HTTP accepts only its distinct file-backed bearer, binds to loopback, and validates Host and Origin; it is not a public remote listener.
• Inherited HTTP proxy settings, redirects, and model-supplied URLs are ignored or rejected.
• Internet targets require HTTPS and public DNS addresses. LAN targets must stay inside the private networks listed in their profile.
• Direct Manager recovery always uses authenticated HTTPS.
• Pandrator application access and Manager recovery use separate credentials that can be revoked independently.
• A changed server identity fails closed until the owner verifies and pins the replacement.
• Work and event tools return bounded, redacted projections rather than raw job payloads or secrets.

Agents can read the packaged pandrator://guide/security-boundaries guide for the same rules while they work.

Generation operations and compact discovery (0.6.2)

Generation/regeneration receipts expose a stable generation_operation_id. pandrator_get_generation_operation follows admission into synthesis and returns terminal audio coverage; pandrator_get_generation_run_coverage reads that coverage for a saved version. Work completion and whole-project audio availability are separate. Existing get_work clients remain supported.

Voice discovery accepts view="compact" and an optional safe fields projection. Workflow/export planning accepts response_mode="structured"; plan creation is advertised as a snapshot write. Dispatch/orchestration native schemas use ordinary object properties, documenting cross-field execution constraints while retaining strict runtime validation. The portable input schemas retain JSON Schema conditionals. Shared server guidance is short; packaged workflow guides supply details on demand. Pronunciation CRUD is now available with scopes and revision checks, and dictionary edits describe their effects on saved speech/audio.