Skip to content

Tools & spend policy

This page describes the MCP tools exposed by openquantum-mcp and the credit safeguards the server enforces.

Tool reference

Account & discovery

Tool Description
list_organizations Organizations for the authenticated account
get_credits Spark and Full balances. Uses organization_id, else OPENQUANTUM_ORGANIZATION_ID, else the first org
list_backends Backend classes with optional filters (online_only, device_type, name_contains, max_qubits). Each row includes spark_available (public miner seen in 15 minutes). qubits is read from the class document and cached for the MCP process
get_backend Details for one backend (short code or UUID). Constraint docs are summarized. When the class has a calibration URL, constraint_summary uses that current calibration (enabled qubits and the narrowed coupling map). configuration_options lists the job fields for that QPU or simulator
list_job_categories Categories and subcategories for job_subcategory_id

Job lifecycle

Tool Description
prepare_job Upload OpenQASM (qasm string or file_path), prepare a quote; does not create the job or spend credits
submit_job Create a job from a preparation_id or one-shot (backend + circuit). Does not wait for completion
get_job Single status fetch, including the job name, cancel_requested, and Proof of Trust proof when one was accepted
list_jobs Recent jobs for an organization, including provider, plan name, message, cancel_requested, and completion time
wait_for_job Poll until terminal status or timeout (default from OPENQUANTUM_MCP_WAIT_TIMEOUT_SECONDS, 600s). On timeout, returns current status so the agent can re-poll
get_job_results Download and summarize output (bitstring counts when present; compact fallback otherwise)
get_job_calibration Download calibration only when requested (not part of default results)
cancel_job Pending cancels immediately. Queued stays Queued until the provider confirms the task never started

Circuit input

  • Prefer OpenQASM text via qasm, or a local file_path readable by the MCP process.
  • Default job_subcategory_id is oth:oth if omitted.
  • Default shots: 100 (override per call or with OPENQUANTUM_MCP_DEFAULT_SHOTS).
  • Jobs are tagged submitted_with=mcp for platform analytics.

Local file paths

file_path is read by the MCP process and uploaded to the platform. Anything the process user can read can leave the machine if an agent is tricked into passing that path as a “circuit.” Prefer inlining QASM via qasm when possible, and run the server with least privilege. Invalid QASM is rejected later by the scheduler — after the bytes have already been uploaded.

Backend configuration

get_backend returns configuration_options, parsed from the backend class schema, and constraint_summary. Each option has key, title, type, required, default, description, minimum, maximum, choices, and visible_when.

constraint_summary includes qubit width, native operations, and the coupling map. When the class publishes calibration_data_url, the server downloads that oq-cal document and applies it the same way the Qiskit plugin builds a Target: enabled qubits narrow the seed coupling map, and the summary reports calibration_applied: true. A failed download keeps the seed document. calibration_updated_at stays on the backend object. Job execution snapshots are still a separate call, get_job_calibration.

  • A choice's value is what the job submits. title is the label.
  • visible_when is empty when the field always applies. Otherwise include that field only when every {key, value} entry matches the configuration you send.
  • prepare_job and one-shot submit_job take configuration_data. The server copies those fields and writes shots into the same object. It leaves schema defaults unset, including conditional fields such as Quantum Rings threshold.
  • When shots is omitted and configuration_data.shots is set, that value is used. When both are set they must match. When both are omitted, shots default to 100.
  • Simulators require engine as well as shots. Read configuration_options for the backend you selected before preparing. A preparation_id already carries its configuration, so configuration_data on submit_job applies only to the one-shot path.

Execution plan & queue priority

Both prepare_job and submit_job accept:

Parameter Default Accepted values
execution_plan auto auto, public, private, or a raw execution-plan UUID
queue_priority auto auto, standard, priority, instant, or a raw queue-priority UUID
  • auto plan: the server prefers Public so Spark credits can apply when available, then lowest cost among remaining options.
  • Force Spark-eligible jobs: pass execution_plan="public". Private plan spend uses Full credits and requires confirm_spend=true.
  • Queue priority changes price via the quote’s per-priority increase; auto picks the cheapest valid priority for the selected plan.

Prepare response: quote & spend preview

prepare_job returns (among other fields):

Field Meaning
estimated_credits Cost for the selected plan + priority
execution_plan_name / queue_priority_name Human-readable selection
quote_summary All quote plans with base price and each queue priority’s price_increase / total, plus which pair is selected
spend_preview Whether submit would auto-approve, need confirm_spend, and the policy message

Agents that need to choose Instant vs Standard (or compare Public vs Private) should read quote_summary before calling submit_job.

  1. get_credits / list_backends
  2. get_backend and read configuration_options
  3. prepare_job with configuration_data → review estimated_credits, quote_summary, and spend_preview
  4. submit_job with confirm_spend=true when required
  5. wait_for_job (repeat if still queued)
  6. get_job_results
  7. get_job_calibration only if needed

Spend policy

Open Quantum has two credit types: Spark (promotional / free tier, Public plan) and Full (purchased). See Credits.

The MCP server applies:

Rule Behavior
Hard cap Estimated cost > 10 credits is rejected (override with OPENQUANTUM_MCP_MAX_CREDITS)
Free jobs Cost 0 proceeds without confirmation
Spark auto-spend Public plan and Spark balance ≥ cost (and ≤ cap) → allowed without confirm_spend
Full credits Private plan, or Public when Spark is insufficient → requires confirm_spend=true

On auto plan selection the server prefers Public so Spark can apply when available.

Warning

Agents can submit jobs quickly. Keep the credit cap low for shared machines, and require explicit confirmation before Full credit spend. Never put SDK secrets in prompts or committed config without a secrets manager.

Multi-organization accounts

If organization_id is omitted, the server uses OPENQUANTUM_ORGANIZATION_ID when that variable is set. Otherwise it uses the first organization returned by the API and reports which org was selected. Pass organization_id explicitly when you belong to more than one org and need a specific one.

Platform limits (reminder)

  • Maximum active jobs per organization (see job lifecycle)
  • Maximum QASM payload size
  • Cancel only in allowed statuses (typically Pending)

Tool errors surface these constraints when the API rejects a call.

Results & calibration

  • get_job_results returns a compact summary suitable for chat context. Bitstring count maps are summarized as top-N outcomes.
  • Set include_raw=true only when you need a truncated raw payload.
  • Calibration is opt-in via get_job_calibration when the completed job has a calibration URL.