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 localfile_pathreadable by the MCP process. - Default
job_subcategory_idisoth:othif omitted. - Default shots: 100 (override per call or with
OPENQUANTUM_MCP_DEFAULT_SHOTS). - Jobs are tagged
submitted_with=mcpfor 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
valueis what the job submits.titleis the label. visible_whenis empty when the field always applies. Otherwise include that field only when every{key, value}entry matches the configuration you send.prepare_joband one-shotsubmit_jobtakeconfiguration_data. The server copies those fields and writesshotsinto the same object. It leaves schema defaults unset, including conditional fields such as Quantum Ringsthreshold.- When
shotsis omitted andconfiguration_data.shotsis set, that value is used. When both are set they must match. When both are omitted, shots default to 100. - Simulators require
engineas well asshots. Readconfiguration_optionsfor the backend you selected before preparing. Apreparation_idalready carries its configuration, soconfiguration_dataonsubmit_jobapplies 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 |
autoplan: 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 requiresconfirm_spend=true. - Queue priority changes price via the quote’s per-priority increase;
autopicks 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.
Recommended agent flow¶
get_credits/list_backendsget_backendand readconfiguration_optionsprepare_jobwithconfiguration_data→ reviewestimated_credits,quote_summary, andspend_previewsubmit_jobwithconfirm_spend=truewhen requiredwait_for_job(repeat if still queued)get_job_resultsget_job_calibrationonly 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_resultsreturns a compact summary suitable for chat context. Bitstring count maps are summarized as top-N outcomes.- Set
include_raw=trueonly when you need a truncated raw payload. - Calibration is opt-in via
get_job_calibrationwhen the completed job has a calibration URL.