Quantum Hardware MCP Server

A production MCP server that gives AI assistants programmatic access to live quantum hardware across IBM Quantum, IonQ, and AWS Braket. Natural language in. Real quantum results out. No dashboards. No manual API calls.

Built in collaboration with Jack Woehr — IBM Quantum veteran, Qiskit contributor.

Why this exists

Quantum researchers lose hours to operational overhead:

• Manually checking which device has the lowest error rate today
• Submitting the same circuit to IBM, then separately to IonQ, then comparing by hand
• Losing reproducibility context between runs — "what was the CX error when I ran Figure 3?"
• No pre-flight — wasting queue time on circuits that fail at transpile
• No cross-provider queue visibility — IBM backlogged for 3 days, IonQ open, no way to know without checking each dashboard manually
• Discovering routing failures only after wasting QPU credits — a degree-4 qubit on heavy-hex silently causes 4× gate inflation

This server eliminates that overhead. Your AI assistant handles device selection, circuit validation, routing overhead prediction, job submission, result retrieval, and amplification analysis through a single interface.

What we discovered running real experiments

We have been using this server to run real quantum experiments on IBM ibm_marrakesh — not just as a demo, but as active research infrastructure. The results changed how we built the server.

The routing failure discovery (Phase 4): We built a 7-qubit Grover circuit to search Pascal's Triangle for rows where 3003 appears. The circuit had 263 logical gates. After transpilation: 1,037 hardware gates. The signal collapsed.

The root cause was not the transpiler. It was graph embedding: one ancilla qubit needed 4 direct connections in the circuit interaction graph. IBM heavy-hex topology allows max 3 connections per qubit. The transpiler had no choice but to inject ~300 SWAP gates (3 CX each) to route around the constraint.

This is now baked into the server as check_routing_overhead — it detects degree-4 violations before you submit.

The LNAA approach (Phase 5): After discovering that Grover's oracle structure creates an unfixable degree-4 node on heavy-hex, we scrapped Grover entirely. Instead of a Boolean oracle, we built an Ising Hamiltonian — the same encoding family behind QAOA and quantum annealing — where target rows (14, 15, 78, found classically via the Lucas-theorem sieve beforehand) are the ground states. IBM's RZZ and RX gates implement this natively — no routing, no SWAP, no ancilla.

Result: 27.78× amplitude amplification, preparing and confirming those already-known target states, with 135 hardware gates on ibm_marrakesh.

Previous best: 4.17× with 103 gates (Phase 3, Grover).

Important honesty note: the sieve (classical, microseconds) finds which rows collide. The quantum circuit doesn't discover that fact — it demonstrates that a hardware-native encoding can prepare and amplify those known target states without routing overhead, at scale, in one job. That's a real result about circuit design and hardware efficiency, not a mathematical discovery. We call the technique LNAA (Lattice-Native Amplitude Amplification) as a name for this specific application of Ising-Hamiltonian encoding to Pascal's Triangle collision search — the underlying math (Ising embeddings, native-gate execution) is well-established, not new. The insight worth keeping — encode targets as ground states, not Boolean conditions, so the circuit matches the hardware's native connectivity — is now the encode_search_problem tool.

Fleet coverage

19 backends across three providers:

All 19 are polled every 2 hours. The dataset grows continuously — ML routing recommendations are planned once 60+ days of data accumulate.

System architecture

graph TD
    User["User / AI Assistant"]

    subgraph Control Plane
        Dispatcher["Dispatcher\nagent-server.js\nRoutes IBM vs IonQ vs Braket"]
        IBMAgent["IBM Subagent\nibm-subagent.js"]
        IonQAgent["IonQ Subagent\nionq-subagent.js"]
    end

    subgraph Execution Plane
        MCP["MCP Server\nserver.py\n34 tools"]
        IBMAPI["IBM Quantum API\nQiskit Runtime"]
        IonQAPI["IonQ REST API"]
        BraketAPI["AWS Braket API"]
    end

    subgraph Observability Plane
        Snapshot["snapshot.py\nRuns every 2h"]
        DB["devices.db\nSQLite — local history"]
        CSV["data/snapshots.csv\nPublic — GitHub Actions CI"]
        Jobs["job_submissions\nAgentic workload log"]
        Report["report.py\nDaily fleet report"]
        Alerts["Calibration drift alerts\nCX / readout / T1 / T2"]
    end

    User --> Dispatcher
    Dispatcher --> IBMAgent
    Dispatcher --> IonQAgent
    IBMAgent --> MCP
    IonQAgent --> MCP
    MCP --> IBMAPI
    MCP --> IonQAPI
    MCP --> BraketAPI
    Snapshot --> DB
    Snapshot --> CSV
    Snapshot --> Alerts
    MCP --> Jobs
    DB --> MCP
    Jobs --> MCP
    Report --> DB

How it works

Step 1 — Request classification The dispatcher reads your message and classifies it: IBM job, IonQ job, or cross-provider comparison. Each subagent sees only the tools for its provider — no accidental cross-wiring.

Step 2 — Pre-flight validation Before touching the queue, debug_circuit catches missing measurements, decoherence bound violations, and qubit count mismatches. circuit_report does a full dry-run transpile — gate counts, qubit mapping, per-pair CX error, estimated fidelity — all without submitting. check_routing_overhead detects degree-4 qubit violations that would cause SWAP flooding.

Step 3 — Credit-aware routing estimate_runtime computes QPU minutes before submission. route_job ranks backends by cost × error rate and picks the cheapest option that meets your fidelity requirement.

Step 4 — Execution submit_job compiles to the backend's native gate set (OpenQASM 2.0 or 3.0), submits, and returns a job_id. job_status and job_results close the loop.

Step 5 — Analysis get_amplification computes the amplification factor directly from a job ID and your marked bitstrings — no manual result parsing.

Step 6 — Observability Every 2 hours, snapshot.py records calibration state across all 19 backends. Drift alerts fire when CX error, readout error, T1, or T2 spikes >20%. repro_score runs KL-divergence across N identical runs to quantify hardware reliability. Every job submission is logged for longitudinal workload analysis.

Tools (39 total)

Device intelligence

Job lifecycle

Pre-flight and cost control

Circuit intelligence (derived from real experiments)

Algorithms and chemistry

Discovery tools (Singmaster pipeline)

Observability

IonQ

Real experiments: Singmaster's Conjecture on IBM hardware

Singmaster's Conjecture asks whether any integer appears 9+ times in Pascal's Triangle. We use this server as active research infrastructure — not a demo. All job IDs are real. All results are reproducible.

Step 4 detail (ibm_fez, job d97fk8t2su3c739i26fg, 4096 shots):

Dominant bitstring: 000011100000111101001110  →  1,396 shots (34.08%)

Decoded rail by rail:
  Rail k=6  bits 00001110  →  row 14   C(14,6) = 3003  ✓
  Rail k=5  bits 00001111  →  row 15   C(15,5) = 3003  ✓
  Rail k=2  bits 01001110  →  row 78   C(78,2) = 3003  ✓

Per-rail amplification: 178.8×   (sim predicted 190.27× — 94% retention)
2nd-best state: 2.17% — target is 25× cleaner than noise

Classical sieve: sieve_singmaster_space searched n=2..50,000 × k=2..200 (~5M values), entirely classically, in seconds. No 9+ appearances found. 3003 is the sole 8-way champion in this range. This doesn't push the boundary of what's known about Singmaster's Conjecture — published classical searches have already gone far beyond this bound. The sieve's role here is to supply known target values for the hardware experiments above, not to contribute new number-theoretic results.

The complete pipeline:

sieve_singmaster_space → encode_4way_collision → IBM QPU → get_amplification

Key insight: IBM heavy-hex is an Ising lattice. RZZ + RX gates are native — zero routing overhead. Encoding targets as ground states of a Hamiltonian outperforms Boolean oracle + diffusion when hardware topology constrains qubit degree ≤ 3.

Full experiment history: singmasters-conjecture

Observability plane — calibration history

snapshot.py runs every 2 hours via GitHub Actions:

Job submissions table — every call to submit_job, run_grover, or run_vqe writes a row:

job_id · provider · backend · tool · circuit_qubits · circuit_depth_raw
circuit_depth_transpiled · shots · agent_loop_iteration
was_preflight_checked · was_ai_corrected · day_of_week · hour_utc

Test suite

python tests/test_all_tools.py

28 checks across all tools. Read-only tools hit the real IBM and IonQ APIs. Write tools are tested against validation paths only — zero QPU credits spent.

Project structure

quantum-hardware-mcp/
├── server.py                      # MCP server — 34 tools
├── snapshot.py                    # Multi-provider calibration snapshot (every 2h)
├── report.py                      # Daily fleet report
├── requirements.txt
├── docker-compose.yml
├── Dockerfile
├── .env.example
├── agent/
│   ├── agent-server.js            # Dispatcher — control plane router
│   ├── chat.js                    # Terminal interface
│   └── subagents/
│       ├── base-subagent.js       # Shared ReAct loop
│       ├── ibm-subagent.js        # IBM specialist
│       └── ionq-subagent.js       # IonQ specialist
├── experiments/
│   ├── singmasters_grover.py      # Phase 1 — Grover, target=6
│   ├── singmasters_3003.py        # Phase 2 — Grover, target=3003, coherence limit
│   ├── phase3_grover_v3.py        # Phase 3 v3 — 103 gates, 4.17×
│   ├── phase4_grover_7q.py        # Phase 4 v1 — 7 qubits, row 78 found
│   ├── phase4_grover_v2.py        # Phase 4 v2 — lossy oracle, routing failure discovered
│   ├── phase5_lnaa.py             # Phase 5 — LNAA, 27.78× amplification (RECORD)
│   └── vqe_h2.py                  # VQE for H2 molecule ground state
├── tests/
│   └── test_all_tools.py          # Smoke test suite
├── data/
│   └── snapshots.csv              # Public calibration history (updated by CI every 2h)
└── .github/workflows/
    └── snapshot.yml               # GitHub Actions: snapshot every 2h

Quick start

Prerequisites: Python 3.10+, Node.js 18+, IBM Quantum account (free), LLM API key.

git clone https://github.com/Lokesh-2025/quantum-hardware-mcp.git
cd quantum-hardware-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cd agent && npm install && cd ..
cp .env.example .env        # add IBM token + LLM key
docker compose up --build   # starts MCP server + agent
node agent/chat.js          # open terminal chat

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "quantum-hardware": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/quantum-hardware-mcp/server.py"]
    }
  }
}

Restart Claude Desktop. All 34 tools appear under the hammer icon.

LLM provider support

Roadmap

Completed

• IBM Quantum tools — device intelligence, job lifecycle, pre-flight, routing
• IonQ support — devices, submit, status, results
• AWS Braket integration — 10 backends in snapshot pipeline
• Multi-agent control plane — dispatcher + IBM/IonQ specialist subagents
• Calibration drift alerts — CX error, readout error, T1, T2
• Reproducibility scoring — KL-divergence across N runs
• Credit-aware routing — QPU cost estimation before submit
• Singmaster Phase 1 — Grover 4.11× (depth 611)
• Singmaster Phase 2 — coherence limit bracketed at depth 16,271
• Singmaster Phase 3 v3 — 4.17× at 103 gates (99.4% reduction from Phase 2)
• Singmaster Phase 4 v1 — 7 qubits, row 78 found, 3.04×
• Singmaster Phase 4 v2 — routing failure diagnosed as graph embedding problem
• Singmaster Phase 5 LNAA — 27.78× amplification, 135 gates
• check_routing_overhead — degree>3 detection before SWAP flood
• encode_search_problem — Boolean conditions → Ising Hamiltonian coefficients
• estimate_hardware_gates — predicts transpiled gate count + noise floor warning
• get_amplification — amplification factor from job ID + marked bitstrings
• best_qubits connectivity check — warns when top qubits aren't physically linked
• Temporal indexing — day_of_week + hour_utc on all snapshots and jobs
• Job submissions table — transpilation expansion ratio tracking
• Listed on Glama, mcp.so, PulseMCP
• encode_collision_problem — auto-finds C(n1,k1)=C(n2,k2) pairs, encodes as Ising (122.92× sim)
• run_parallel_collision_search — N simultaneous LNAA rails in one hardware job (~300× ibm_kingston)
• sieve_singmaster_space — Lucas theorem sieve, validated 3003 at 8 positions, searched n=50k
• encode_4way_collision — multi-column parallel LNAA, 178.8× on ibm_fez — first hardware-confirmed 4-way Pascal collision
• Singmaster Step 3 — ~300× amplification, 30 qubits, ibm_kingston
• Singmaster Step 4 — 178.8× amplification, 24 qubits, ibm_fez (hardware record)

Next

• Web interface — visual frontend for device comparison, job submission, circuit playground, live results (in progress: quantum-hardware-web)
• inject_topological_walk — bypass transpiler using calibration DB, map directly to high-coherence qubits
• discover_energy_landscape — LNAA parameter sweep → full energy landscape visualization
• algorithm_selector — decides Grover vs LNAA based on circuit + hardware analysis
• VQE on real IBM hardware — H2 hardware result
• Quantum Rush Hour detection — weekly queue seasonality
• Smart routing brain — cross-provider ML recommendations
• Publication package generator — job ID → figures + BibTeX + methods section

License

MIT — see LICENSE.