MCP Tools Reference

Complete reference for all tools exposed by the QCOS MCP server.

---

QCOS tools

qcos_list_backends

List all available quantum backends with live calibration status and qubit counts.

Parameters: none

Returns:

{
  "backends": [
    {
      "id": "ibm-brisbane",
      "provider": "ibm",
      "qubits": 127,
      "status": "online",
      "drr_score": 91,
      "queue_depth": 4,
      "calibration_age_minutes": 8
    }
  ]
}

---

qcos_submit_circuit

Submit a quantum circuit for execution.

Parameters:

Name	Type	Required	Description
circuit	string	Yes	Circuit in OpenQASM 3 or Qiskit JSON serialized format
backend	string	Yes	Backend ID from qcos_list_backends
shots	integer	No	Number of shots (default: 1024, max: 100000)
optimization_level	integer	No	0–3 (default: 1)
wait_for_result	boolean	No	Poll until complete (default: false)

Returns:

{
  "job_id": "job_abc123",
  "status": "queued",
  "estimated_wait_seconds": 45,
  "drr_preview": { "score": 87, "signal": "GREEN" }
}

---

qcos_get_job_result

Retrieve the result of a completed job.

Parameters:

Name	Type	Required	Description
job_id	string	Yes	Job ID from qcos_submit_circuit

Returns:

{
  "job_id": "job_abc123",
  "status": "completed",
  "counts": { "00": 512, "11": 511, "01": 1 },
  "shots": 1024,
  "drr": {
    "score": 91,
    "signal": "GREEN",
    "confidence": 0.94
  },
  "backend": "ibm-brisbane",
  "execution_time_ms": 3200,
  "proof_hash": "sha256:a1b2..."
}

---

qcos_get_job_status

Check the status of a job without waiting for completion.

Parameters: job_id: string

Returns: { "job_id": "...", "status": "queued|running|completed|failed", "progress": 0.0–1.0 }

---

qcos_cancel_job

Cancel a queued or running job.

Parameters: job_id: string

Returns: { "cancelled": true, "job_id": "..." }

---

qcos_run_vqe

Run a Variational Quantum Eigensolver workflow for molecular energy estimation.

Parameters:

Name	Type	Required	Description
molecule	string	Yes	Molecule formula (H2, LiH, H2O, etc.)
backend	string	Yes	Backend ID
ansatz	string	No	UCCSD (default), RealAmplitudes, EfficientSU2
optimizer	string	No	COBYLA (default), SLSQP, SPSA
max_iterations	integer	No	Default: 100

Returns:

{
  "ground_state_energy_hartree": -1.137,
  "convergence_achieved": true,
  "iterations": 67,
  "drr_score": 88,
  "circuit_depth": 14
}

---

qcos_run_qaoa

Run a QAOA workflow for combinatorial optimization.

Parameters:

Name	Type	Required	Description
problem_type	string	Yes	maxcut, tsp, portfolio, qubo
problem_data	object	Yes	Problem definition (graph, constraints, etc.)
backend	string	Yes	Backend ID
depth	integer	No	QAOA circuit depth (default: 2)

Returns:

{
  "solution": [1, 0, 1, 0],
  "objective_value": 3.0,
  "approximation_ratio": 0.89,
  "drr_score": 85
}

---

qcos_get_drr_score

Get the Decision Reliability Rating for a specific backend and circuit without running it.

Parameters: circuit: string, backend: string

Returns: { "score": 87, "signal": "GREEN", "recommendation": "Safe to execute" }

---

qcos_get_backend_calibration

Get detailed live calibration data for a backend.

Parameters: backend_id: string

Returns: Full calibration JSON with per-qubit gate errors, T1/T2 times, and readout errors.

---

QuantumLock tools

quantumlock_generate_key

Generate a post-quantum key pair.

Parameters:

Name	Type	Required	Description
algorithm	string	Yes	ML-KEM-768, ML-KEM-1024, Kyber-512
label	string	No	Human-readable name
bind_to_device	string	No	Device fingerprint for hardware binding

Returns:

{
  "key_id": "key_xyz789",
  "public_key": "...",
  "algorithm": "ML-KEM-768",
  "created_at": "2026-03-30T12:00:00Z",
  "chain_of_trust": "sha256:c3d4..."
}

---

quantumlock_verify_license

Verify a hardware-bound license artifact.

Parameters: artifact_id: string, device_fingerprint: string

Returns: { "valid": true, "expires_at": "2027-01-01", "proof": "sha256:..." }

---

quantumlock_revoke_key

Revoke a key or license artifact immediately.

Parameters: key_id: string, reason?: string

Returns: { "revoked": true, "effective_at": "2026-03-30T12:01:00Z" }

---

quantumlock_get_key_status

Check the status of a key (active, revoked, expired).

Parameters: key_id: string

---

quantumlock_create_license

Create a hardware-bound software license artifact.

Parameters: product: string, customer_id: string, device_fingerprint: string, expires_at?: string

---

quantumlock_list_keys

List all keys and licenses for the authenticated account.

Parameters: status?: "active"|"revoked"|"expired", limit?: integer

---

SynapseX tools

synapsex_rerank

Rerank a list of documents using quantum-enhanced similarity scoring.

Parameters:

Name	Type	Required	Description
query	string	Yes	The search query
documents	array<string>	Yes	List of documents to rerank
top_k	integer	No	Return top N results (default: all)
model	string	No	Reranking model (default: synapsex-rerank-v1)

Returns:

{
  "results": [
    { "index": 2, "score": 0.94, "document": "..." },
    { "index": 0, "score": 0.87, "document": "..." }
  ],
  "model": "synapsex-rerank-v1",
  "quantum_backend_used": "ibm-brisbane"
}

---

synapsex_embed

Generate embeddings using a SynapseX model.

Parameters: text: string | array<string>, model?: string

Returns: { "embeddings": [[...], ...], "model": "..." }

---

synapsex_complete

Run inference against a deployed SynapseX model.

Parameters: prompt: string, model: string, max_tokens?: integer, temperature?: number

---

synapsex_list_models

List available models on the SynapseX server.

Parameters: none

Returns: Array of model objects with IDs, capabilities, and context lengths.

---

Error codes

All tools return structured errors:

{
  "error": {
    "code": "BACKEND_UNAVAILABLE",
    "message": "ibm-brisbane is currently offline for maintenance",
    "retry_after_seconds": 300
  }
}

Code	Meaning
INVALID_CIRCUIT	Circuit failed validation
BACKEND_UNAVAILABLE	Backend is offline or at capacity
INSUFFICIENT_CREDITS	Account quota exceeded
DRR_ABORT	Circuit aborted — DRR score below threshold (RED signal)
AUTH_INVALID	API key missing or invalid
RATE_LIMITED	Too many requests