FlagQuantum MCP Server

Report gate counts, depth and wire usage for one circuit. Gate counts and depth are self-explanatory; the rest of the analysis is worth stating. wire_usage has one entry per wire, counting the instructions that touch it, so a two-qubit gate counts on both of its wires. two_qubit_gates counts width-2 instructions and multi_qubit_gates counts width-3-and-up, so a cx is two-qubit and not multi. max_gate_width is the widest single instruction, and channel_count counts instructions marked as channels in metadata, with has_noise being channel_count > 0.

Substitute values for a circuit's parameters. The result is no longer parameterized, so it can be exported. Export is the only step that needed this: analysis, optimization, routing, drawing and plan_execution_tool all accept a parameterized circuit as-is, because none of them reads a parameter value. The values are yours to choose, and a chosen value is not a result: say which gates carry parameters and what values you assumed, whenever a number downstream depends on them. inspect_parameters_tool reports which gates carry a parameter and what it is named, so nothing has to be inferred.

Route one circuit onto several topologies and compare the cost. One entry per topology, each with its routed gate count, depth and SWAP overhead, plus which topology was cheapest on those measures.

Compile and optionally route a circuit through the complete SDK pipeline. Use this when the desired result is one deployable circuit rather than a topology comparison. With topology="none" the SDK only performs target-independent compilation. Choose line, ring, grid or custom to make every two-qubit gate legal on that connectivity in the same call.

Describe one exact installed research capability. Use the returned request, result, validator, target, limitation and schema identities; do not infer support from this tool description.

Describe gates: wire count, parameter names, aliases and kind. Call this before writing a gate list by hand. A gate's signature is not part of the circuit format, so this is the only place to learn that ``rz`` takes one parameter named ``theta`` while ``u3`` takes three.

Decompose a circuit into the layers it can execute in. Gates in one returned layer run concurrently, so n_layers is the circuit's depth: it is the longest chain of gates that cannot be reordered.

Describe a coupling map before routing onto it. For each requested pair the result gives the shortest path and its distance, where distance is the number of edges on that path — the number of SWAPs a naive route would need, so adjacent wires are distance 1. Omit ``pairs`` to measure adjacent wires.

Validate IR JSON and report whether it round-trips unchanged. ``round_trip_stable`` compares the text you sent against FlagQuantum's canonical serialization, which is compact. It is about your input, not about ``indent``: asking for indented output does not change it.

Draw a circuit as text. A symbol is rendered as the SDK's repr of it, so ``RY(theta)`` appears as ``RY(Parameter(name='theta'))``. That is the symbol, not a broken value: FlagQuantum's ``Parameter`` defines no ``__str__``.

Render a circuit as OpenQASM 2.0 or 3.0 text. The result measures every wire unless ``result_wires`` says otherwise, so the emitted text usually carries measurements that the source circuit does not. ``content_hash`` identifies that source circuit, not the text.

Render a circuit as QCIS text. A circuit containing an arbitrary matrix gate comes back as an error rather than as text, because QCIS has no way to express one. Report that refusal rather than silently substituting a different gate: a circuit that exports successfully because a gate was swapped is not the circuit the caller wrote, and nothing in the text would say so.

Estimate a bounded request with FlagQuantum before execution. The upstream estimate is authoritative; this adapter adds no quantum cost model. Stop if the returned estimate is not supported.

Return a time-resolved local Lindblad density-matrix trajectory. Uses the same contract as ``plan_evolution_tool``. The response has exactly one population row per requested time, requested observable trajectories, optional density matrices, maximum trace drift, a population-bound check, and honest numerical method/order/step-size/precision metadata. Execution is deterministic and local to this CPU process; it never contacts hardware or a provider.

Execute one validated capability on the bounded local CPU path. Pass provider_order exactly and explicitly authorize unavailable-only fallback when requesting more than one provider. This tool never reads credentials, submits hardware or accesses paid resources. Inspect the Evidence Bundle status and validators, then call validate_evidence_tool; transport success is not scientific success.

Report whether a circuit is parameterized, and where each symbol sits. A symbol is written ``{"theta": {"$parameter": "theta"}}`` in either input format. A bare string is not a symbol: it is a value, and the circuit would report itself as unparameterized, so it is rejected instead.

Apply target-independent optimizations and report what changed.

Validate and size a deterministic continuous-time Lindblad evolution. Hamiltonian terms and observables use Pauli descriptors such as ``{"pauli": "X", "coefficient": 0.5, "wires": [0]}``. The initial state may be a basis bitstring such as ``"1"`` or a dense statevector or density matrix. Collapse entries name ``"amplitude_damping"`` (or ``"sigma_minus"``), a non-negative physical rate, and one wire. Rates, Hamiltonian coefficients and time values share one inverse-time unit; rates are not per-instruction probabilities. Times must be finite and strictly increasing. This tool validates only and performs no evolution. It runs locally on CPU with no network, credentials, provider or hardware access. Returns: Matrix dimension, trajectory memory, time-point count, numerical method, order, integration step size, precision and local provenance.

Plan execution without running anything. Nothing is executed and no state is allocated: the result is the resolved execution contract (mode, backend, device, precision) plus a summary carrying depth, state_bytes, shardable_wires and the claim fields (claim_evidence_type, scalability_claim_allowed, release_gate_allowed) that say what this plan does and does not license. To actually run the circuit locally, call simulate_circuit_tool with the same options and outputs.

Route a circuit onto a coupling map, inserting SWAPs where needed. The SWAP overhead is reported as ``instruction_delta``: a non-zero delta means the routed circuit is not the same size as the source, so it should not be described as equivalent to it.

Search the installed structured research capability catalog. Start here; an empty query lists the bounded local candidates. This tool discovers capabilities only and does not execute quantum work.

Canonicalize a circuit into FlagQuantum IR JSON. Accepts either input format and always answers with the canonical "ir" form, so a circuit written as a gate list gains a version and a content hash.

Run a circuit locally and return the outputs it was asked for. This is the only tool here that executes anything, and it executes in this process on CPU: no network, no credentials, no provider. The engine is chosen by options["mode"], and all five default-install engines are reachable — "statevector" (the default), "mps", "tensor_network", "density_matrix" and "auto". The SDK also accepts "stabilizer", which requires the optional `flagquantum[stim]` dependency and supports shot-based counts or samples, not exact probabilities. These are engines of one local run rather than different places to run, so none of them leaves this process — but they are not interchangeable in cost, and the spread is wider than the circuit's width suggests. Measured at 20 wires on a product state, plan_execution_tool's summary reports 8 MB of state for "statevector" and 8.8 TB for "density_matrix". Ask the plan before choosing a non-default mode. The result's "execution" block records the engine that ran, alongside "simulation_engine", "device" and the accuracy contract whose metric is "not_measured" — an ideal simulation is not evidence about any hardware, and this tool does not present it as such. That field holds the engine, not the request: "auto" comes back as whatever the SDK settled on — "statevector", since this tool passes no noise model — rather than as the word "auto". "execution_path" and "platform_provider" read "local_statevector" and "pytorch_cpu" for a statevector run and are empty strings for "mps", "tensor_network", "density_matrix" and "stabilizer", which is how the SDK reports those engines rather than a failure. What is returned, in order of precedence: the outputs you pass; otherwise the circuit's own "measurements" field, which the SDK reads and which carries its own shot count; otherwise probabilities over every wire. Widths that the SDK will not compute a marginal for are refused with the alternatives named. Refused rather than guessed at: a circuit with unbound parameters (bind it first), a circuit carrying "observables" (a local statevector run never evaluates them — ask for an "expectation" output instead), and outputs passed alongside the circuit's own measurements.

Optimize a parameterized circuit's angles against a Pauli-sum energy. This is the gradient step that simulate_circuit_tool cannot take. That tool evaluates an energy; this one improves it. Fifty calls to simulate, each one a guess, is a manual scan; one call here is a descent, because the SDK reports exact gradients for a statevector simulation and this tool uses them. The objective is the Hamiltonian expectation, and it has to be given: the "hamiltonian" argument takes the same term list an "expectation" output takes, one letter per wire. There is no default, because without an objective the number being minimised is not an energy. Runs in this process: a statevector simulation on CPU, no network, no credentials, no provider. The result carries the SDK's provenance and its accuracy contract, which reports metric "not_measured" — an ideal simulation is not evidence about hardware. Refused before starting: a circuit with no parameters, a missing or malformed objective, a starting value that names a parameter the circuit does not have or omits one it does, a step count that is not a positive whole number or a learning rate that is not a positive finite number (either of them too large for a float included), a circuit carrying "observables" (never read — put the objective in "hamiltonian"), and any run whose predicted cost is past the budget. The prediction is an estimate, not a measurement of your machine. A learning rate that is finite and positive but larger than the optimizer's own arithmetic can hold is not caught before the run — it fails inside the SDK's first update, and the refusal that comes back names "learning_rate" and the rate it overflowed on rather than the circuit. Measured on the SDK installed here, 3.4e37 trains and 4e37 does not, at every width tried; that boundary is float32's maximum divided by ten. Adam at the learning rate you set. Losses are reported one per step, so a caller can see whether the run is still moving; whether it has converged is your reading, not this tool's claim. The parameters it ended on come back as "parameters"; pass those back as "values" to continue a run rather than restart it.

Validate a complete typed research request before execution. Continue only when the upstream report passes. MCP transport success is not an applicability decision.

Validate an Evidence Bundle with the installed FlagQuantum validator. Preserve this report for independent client or researcher acceptance. The operation does not turn transport completion into a scientific conclusion.