Documentation

Quantum computing and optimization tools for AI coding assistants and HTTP clients. 19 tools, 7 simulator backends, 5 optimization solvers.

Getting Started

Sign in and create an API key

Go to the sign-in page and authenticate with GitHub.

Navigate to API Keys and click "Create New Key".

Copy the key immediately -- it will only be shown once. Keys start with ql_.

Add the MCP config to your client

Add Qlaude to Claude Desktop, Claude Code, Cursor, or any MCP-compatible client.

Claude Desktop / Claude Code

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

claude_desktop_config.json

{
  "mcpServers": {
    "qlaude": {
      "url": "https://qlaude-production.up.railway.app/mcp/http",
      "headers": {
        "Authorization": "Bearer ql_your_api_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

.cursor/mcp.json

{
  "mcpServers": {
    "qlaude": {
      "url": "https://qlaude-production.up.railway.app/mcp/http",
      "headers": {
        "Authorization": "Bearer ql_your_api_key_here"
      }
    }
  }
}

Replace the API key

Replace ql_your_api_key_here with the actual key you created in Step 1.

Start using quantum tools

Open a new conversation and try these example prompts:

Simulate a Bell State

"Create a 2-qubit Bell state circuit and simulate it with 1024 shots"

Quantum Teleportation

"Build a quantum teleportation circuit that transfers |+> from qubit 0 to qubit 2"

Solve an Optimization Problem

"Solve this knapsack: items [(10kg, $60), (20kg, $100), (30kg, $120)] with capacity 50kg"

Benchmark Solvers

"Generate a 6-qubit peaked circuit and benchmark all heuristic solvers on it"

Simulator Backends

Qlaude supports seven simulator backends. The backend is auto-selected based on your circuit, or you can override it with the backend parameter.

Backend	Engine	Max Qubits	Best For
`numpy`	NumPy	25	Small circuits, full state inspection
`aer`	Qiskit Aer	32	Noise models, mid-size circuits
`stim`	Stim	Millions	Clifford-only circuits at any scale
`qulacs`	Qulacs	33	Best single-node performance for medium circuits
`ddsim`	MQT DDSIM	100+ (structured)	Large structured circuits with low entanglement
`pennylane`	PennyLane Lightning	30	Variational / differentiable circuits
`bluequbit`	BlueQubit (cloud GPU)	34-36	Maximum qubit count (pro+ tier)

Auto-Selection Logic

Clifford-only gates (H, X, Y, Z, S, Sdg, CX, CZ) → stim (any qubit count)

25 or fewer qubits → numpy (exact statevector)

26-33 qubits → qulacs (fast CPU statevector)

More than 33 qubits → ddsim (decision diagrams)

Available Tools

All 19 tools are available via MCP and REST API. Credit cost is shown per call.

Circuit Simulation

simulate_circuit5 cr

Simulate a quantum circuit and get measurement results

parse_qasm1 cr

Parse OpenQASM and return structured gate/register info

visualize_circuit1 cr

Generate ASCII circuit diagram and probability chart

explain_circuit1 cr

Get a plain-language explanation of a circuit

Heuristic Solvers

solve_peaked_circuit10 cr

Find the most probable output bitstrings using heuristic solvers

explain_heuristic1 cr

Explain which solver would be chosen for a circuit and why

benchmark_circuit20 cr

Compare multiple solvers on the same circuit

Circuit Optimization

transpile_circuit2 cr

Optimize a circuit by removing redundant gates and fusing operations

Peaked Circuits

generate_peaked_circuit5 cr

Generate a random circuit with a peaked output distribution

construct_peaked_circuit5 cr

Build a peaked circuit using a specific construction method

analyze_peaked_distribution5 cr

Measure how peaked a circuit's output distribution is

Optimization

solve_optimization15 cr

Solve a combinatorial optimization problem (knapsack, max-cut, QUBO, ILP, graph coloring)

explain_optimization1 cr

Analyze an optimization problem and recommend a solver

list_optimization_solversfree

List all available optimization solvers and their capabilities

get_formulation_guidefree

Get guidance on how to structure a problem for a specific solver

Circuit Library

list_circuit_templatesfree

List all available pre-built circuit templates

load_circuit_template5 cr

Load a circuit template by name with custom parameters

Cloud Simulator

run_cloud_simulator25 cr

Run a circuit on cloud quantum hardware (pro+ tier)

Account

creditsfree

Get current credit balance, daily allowance, and usage breakdown

REST API Reference

Base URL: https://qlaude-production.up.railway.app/api/v1

Authenticate every request with a Bearer token: Authorization: Bearer ql_YOUR_API_KEY

Circuit Endpoints

Method	Path	Description	Credits
POST	`/simulate`	Simulate a circuit and get measurement results	5
POST	`/parse`	Parse OpenQASM and return gate/register info	1
POST	`/visualize`	Generate ASCII circuit diagram and probability chart	1
POST	`/explain`	Get a plain-language explanation of a circuit	1
POST	`/transpile`	Optimize a circuit by removing redundant gates	2

Heuristic Solver Endpoints

Method	Path	Description	Credits
POST	`/solve-peaked`	Find top bitstrings using heuristic solvers	10
POST	`/explain-heuristic`	Explain which heuristic would be selected and why	1
POST	`/benchmark`	Compare multiple solvers on the same circuit	20

Peaked Circuit Endpoints

Method	Path	Description	Credits
POST	`/generate`	Generate a random peaked circuit	5
POST	`/construct-peaked`	Build a peaked circuit using a specific method	5
POST	`/analyze-peaked`	Measure how peaked a circuit's output distribution is	5

Optimization Endpoints

Method	Path	Description	Credits
POST	`/optimize`	Solve a combinatorial optimization problem	15
POST	`/explain-optimization`	Analyze a problem and recommend a solver	1
POST	`/formulation-guide`	Get guidance on structuring a problem for a solver	0
GET	`/optimization-solvers`	List all optimization solvers and capabilities	0

Library Endpoints

Method	Path	Description	Credits
GET	`/circuit-templates`	List all available circuit templates	0
POST	`/circuit-templates/load`	Load a circuit template with custom parameters	5

Hardware & Account Endpoints

Method	Path	Description	Credits
POST	`/cloud-simulate`	Run a circuit on cloud quantum hardware (pro+ tier)	25
GET	`/credits`	Get credit balance, allowance, and usage breakdown	0

Example: Simulate a Circuit

curl

curl -X POST https://qlaude-production.up.railway.app/api/v1/simulate \
  -H "Authorization: Bearer ql_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "circuit_qasm": "OPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\ncreg c[2];\nh q[0];\ncx q[0],q[1];\nmeasure q -> c;",
    "shots": 1024
  }'

Optimization Solvers

Five solvers are available. The solver is auto-selected based on your problem, or you can specify one with the solver parameter. Problem types: knapsack, max-cut, graph coloring, QUBO, ILP.

Solver	Type	Input Format	Max Variables	Best For
`scipy_lp`	Exact	ILP	Unlimited	Knapsack, ILP, linear constraints
`simulated_annealing`	Approximate	QUBO	Unlimited	Large QUBO, max-cut, graph coloring
`exact_solver`	Exact	QUBO	20	Small QUBO, guaranteed optimum

Auto-Selection Logic

Naturally linear (knapsack, ILP) → scipy_lp

QUBO with 20 or fewer variables → exact_solver

QUBO with more than 20 variables → simulated_annealing

Credits & Pricing

Each tool call costs a fixed number of credits. Credits reset daily at midnight UTC.

Daily Allowances

Tier	Daily Credits
Free	500
Pro	5,000
Enterprise	50,000

Cost Breakdown

Cost	Tools
0 credits	`list_circuit_templates`, `list_optimization_solvers`, `get_formulation_guide`, `credits`
1 credit	`explain_circuit`, `explain_heuristic`, `explain_optimization`, `visualize_circuit`, `parse_qasm`
2 credits	`transpile_circuit`
5 credits	`simulate_circuit`, `generate_peaked_circuit`, `construct_peaked_circuit`, `analyze_peaked_distribution`, `load_circuit_template`
10 credits	`solve_peaked_circuit`
15 credits	`solve_optimization`
20 credits	`benchmark_circuit`
25 credits	`run_cloud_simulator` (pro+ tier)

Supported Gates

All circuits use OpenQASM 2.0. Circuits using only Clifford gates (H, X, Y, Z, S, Sdg, CX, CZ) can be simulated at any scale via Stim.

Gate	QASM	Description
Hadamard	`h`	Creates superposition; maps \|0> to equal mix of \|0> and \|1>
Pauli-X	`x`	Bit flip; equivalent to a classical NOT
Pauli-Y	`y`	Combined bit and phase flip
Pauli-Z	`z`	Phase flip; leaves \|0> unchanged, flips sign of \|1>
S	`s`	Quarter-turn phase gate (90 degrees)
S-dagger	`sdg`	Inverse of the S gate (-90 degrees)
T	`t`	Eighth-turn phase gate (45 degrees)
T-dagger	`tdg`	Inverse of the T gate (-45 degrees)
CNOT	`cx`	Controlled-NOT; flips target if control is \|1>
CZ	`cz`	Controlled-Z; phase flip if both qubits are \|1>
Toffoli	`ccx`	Controlled-controlled-NOT; three-qubit AND-like gate
RX	`rx(theta)`	Rotation around X axis by angle theta
RY	`ry(theta)`	Rotation around Y axis by angle theta
RZ	`rz(theta)`	Rotation around Z axis by angle theta
Identity	`id`	No operation; leaves qubit unchanged

Limits

Limit	Value
Max qubits (exact simulation, numpy)	25
Max qubits (fast statevector, qulacs)	33
Max qubits (decision diagrams, ddsim)	100+ (structured)
Max qubits (Clifford-only, stim)	Millions
Max qubits (peaked circuit generation)	12
Max qubits (cloud hardware CPU, admin)	34
Max qubits (cloud hardware GPU, admin)	36
Circuit simulation timeout	30 seconds
Optimization solver timeout	60 seconds
Max measurement shots	100,000
Max top_k (solve, benchmark)	1,000
Max optimization variables (exact solvers)	20
Daily credits (Free tier)	500
Daily credits (Pro tier)	5,000
Daily credits (Enterprise tier)	50,000
Credit reset time	Midnight UTC

Error Codes

All error responses return JSON with a detail field describing the error.

Status	Error	When
400	Bad Request	Missing required fields, invalid JSON, parameter out of range
401	Unauthorized	No Authorization header, malformed key, revoked key
402	Payment Required	Credit balance too low for the requested tool
403	Forbidden	User below pro tier calling run_cloud_simulator
422	Unprocessable Entity	Invalid OpenQASM syntax, unsupported gates
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Backend error, timeout, unexpected failure

Error response example

{
  "detail": "Insufficient credits: need 5 for simulate_circuit, have 3. Resets at midnight UTC."
}

Need help?

Check out the GitHub repo for source code, examples, and issue tracking.

View on GitHub