Preview: Python 3.12, Claude Agent SDK 0.2.160, MCP 2.2.0 and Pydantic 2.13.5. Local tests cover the actual SDK MCP server and protocol with a simulated HTTP API. Claude CLI/model execution, live credentials and real-source acceptance remain unverified.
Canonical submission and original-command recovery
Use POST /v1/quotes, then POST /v1/tasks with productId, the approved input, the quoted expectedPricingVersion, and the canonical Idempotency-Key. The host creates a key once for explicitly approved new work, using new_command_key() from the bundled REST engine, and persists it with the approved input before submission. Keys have the form v1.<13-digit Unix milliseconds>.<22–64 base64url characters>. Do not generate keys in model arguments or a workflow retry expression.
Creation requires allow_write=True, the persisted request_key, and explicit command_mode="new". The default command_mode="recover" performs an original-command GET and never obtains another quote or submits again. Repeated invocation in the same new-intent toolset also reads the original after its first submission attempt. Changed input is refused. After a restart or any lost response, use this host-only path; it needs no input, quote or model call:
import os
from truefetch_rest import recover_command, observed_task_id
original = recover_command(
os.environ["TRUEFETCH_API_KEY"], "tasks.create", os.environ["TRUEFETCH_COMMAND_KEY"]
)
if original["receipt"]["outcome"] == "accepted":
saved_task_id = observed_task_id(original)
# Persist the reference before reading the existing task/results.HTTP 200 is not acceptance. Inspect receipt.outcome: accepted supplies an authoritative task reference even when the current task projection is null; processing and unknown require another explicit original GET, respecting the returned retry interval. rejected and not_accepted_final establish nonacceptance and require deliberate new work if you still want a collection. receipt_expired remains unconfirmed: inspect Tasks or contact support. The helper never seals, replays a POST or creates a replacement key. The server accepts new keys for 24 hours, allows five minutes of future clock skew, and retains terminal receipts for at least seven days; it can still answer a retained original after the new-command window ends. A current Task state does not establish a particular command’s outcome.
Cancellation is a separate command: bind a different persisted canonical cancel_key for the newly created task, or pass cancel_task_ids=(saved_task_id,) and cancel_command_keys={saved_task_id: saved_cancel_key} for an explicitly approved saved target. POST /v1/tasks/{taskId}/cancel sends {} and that cancellation key. Unknown cancellation is recovered with recover_command(api_key, "tasks.cancel", saved_cancel_key), never the creation key. Acceptance of cancellation does not promise the task ended as cancelled. The budget, keys and cancellation mapping remain host-only arguments.
Download and configure
Save all five files in one directory and install the pinned requirements in a virtual environment:
Keep your TrueFetch key in the host environment. Configure supported Claude authentication separately, choose a model explicitly and provide an isolated working directory. This example uses an in-process SDK MCP server; it does not require TrueFetch’s remote MCP service to be enabled.
Host-controlled actions
Read-only mode exposes usage, estimates, saved task results and task listing. The host must explicitly enable collection with a write key, fixed credit ceiling and saved request key. The creation tool checks a fresh estimate and pricing version before submitting. Persist its task ID immediately. Original recovery performs GET with the same key; changing the key creates another intent.
Collection reserves credits and can incur charges. Claude’s model budget is separate from TrueFetch credits. Cancellation only covers IDs created by this toolset or explicitly allowed by the host. Reading a task never grants cancellation permission.
Permissions and session limits
The sample configures no built-in tools, strict explicit MCP configuration, empty settings sources/skills/plugins and a callback denying unrelated tools. The allowed-tools list pre-approves TrueFetch tools; it is not itself a tool-removal mechanism. No permission bypass mode is used. Verify actual CLI enforcement before enabling writes.
The host limits model turns, tool calls and elapsed time. Tool errors prevent further execution through the toolset. A successful model response is not proof of complete collection. The wrapper starts a new session; it does not automatically resume sessions with possibly stale permissions.
Recover complete results
Use a fresh Toolset and await reader.recover(saved_task_id) outside the model loop. It checks every page, task identity, terminal status, counts, ordering and cursor progress. A complete return contains task, data, complete and partial. Source outcomes and expiry remain in task metadata. A single page or model summary is not a complete export; full pagination does not promise exhaustive source coverage.
Stopping the local session cannot guarantee cancellation of an in-flight HTTP thread or remote task. Late acceptance may not appear in returned IDs. Preserve the original key/input and inspect your workspace before starting another collection. No automatic collection retry or cancellation is performed. Expired results, budget, pricing and authentication failures need inspection.
Use a dedicated runtime with only necessary credentials. The subprocess override clears TRUEFETCH_API_KEY, but is not a general secret filter. CLI session files, logs, telemetry and provider retention require separate configuration. Tool arguments and pages go to the configured model in a real run; source descriptions remain untrusted data. Local protocol tests do not prove prompt-injection resistance or model behavior.
Full setup · Job Search API · All integrations · Official custom-tools documentation
The shared REST reader requires UTF-8 JSON and rejects nonfinite numbers, including numeric overflow. Interrupted or oversized HTTP error bodies keep a redacted HTTP-status diagnostic, and truncated successful transfers fail without returning data. It also rejects duplicate member names within an object, including names written with equivalent Unicode escapes; repeated names in separate records are allowed. Recovery also rejects nonfinite values from tool output instead of marking the export complete. Preserve the saved task ID and original request key after an error; these checks do not create or retry collection.
For each available result page, the reader checks the task again after receiving the page, including the final page. This adds one read-only task GET per page. Changed identity, status, availability or count, or a failed recheck, prevents a complete export. The check is a point-in-time observation; files can expire or become unavailable afterward.
Before collection, the creation tool checks that the estimate matches the requested input and that reserved billing units equal the record limit multiplied by the unit price. Amounts must be positive ASCII integers, and the reservation must fit the host credit budget. Invalid estimates stop before submission; server-side pricing and budget checks still apply.