FlagQuantum MCP Server

An MCP server that gives any MCP-compatible agent local access to the FlagQuantum SDK: build, compile, route, serialize and plan quantum circuits, with no credentials, no network access and no hardware submission.

Part of FlagQuantum/mcp-servers.

The mcp-name comment above is not decoration: the MCP Registry reads it from this README to verify that whoever publishes the registry entry also controls the PyPI package. Removing it breaks registry publishing.

What it does

Fifteen read-only tools over stdio.

Build and inspect

Parameters

Compile and route

Export and present

Three resources: flagquantum://version (versions of the server, the SDK and the IR contract), flagquantum://gate-set (every gate with its wire count and parameter names) and flagquantum://ir-schema (the IR envelope, shown by example from a real serialization).

Three prompts: build_and_analyze_circuit, compile_for_topology, export_circuit.

Install

pip install flagquantum-mcp-server

This pulls flagquantum, which depends on torch.

Claude Code

claude mcp add flagquantum -- uvx flagquantum-mcp-server

Claude Desktop / Cline

{
  "mcpServers": {
    "flagquantum": {
      "command": "uvx",
      "args": ["flagquantum-mcp-server"]
    }
  }
}

MCP Inspector

npx @modelcontextprotocol/inspector uvx flagquantum-mcp-server

Circuit formats

Two input formats are accepted, both of them FlagQuantum's own serialization.

ir (canonical) — FlagQuantum IR JSON, as produced by CircuitIR.to_json(). Versioned, hashable, and rejected if it carries unknown fields:

{
  "kind": "flagquantum.circuit_ir",
  "version": "1.0",
  "n_wires": 2,
  "dtype": "complex64",
  "shape": [4],
  "instructions": [
    {"opcode": "h", "wires": [0], "params": {}, "matrix": null, "metadata": {}},
    {"opcode": "cx", "wires": [0, 1], "params": {}, "matrix": null, "metadata": {}}
  ],
  "observables": [],
  "measurements": [],
  "metadata": {}
}

qir (convenience) — the compact gate list from Circuit.to_qir(), easier to write by hand:

[{"name": "h", "index": [0]}, {"name": "cx", "index": [0, 1]}]

The two formats use different key names, and this is the most common mistake: the gate list calls a gate name and its wires index, while serialized IR calls them opcode and wires. Sending IR keys as qir is rejected with a message that says so by name. An empty gate list is also rejected, because the wire count is inferred from the highest index — an empty list describes no circuit. A bare integer is accepted for a single-wire gate ("index": 0 means "index": [0]).

Either format can be passed to any tool; serialize_circuit_tool converts qir into canonical ir.

circuit_format is a closed set — the JSON schema publishes "enum": ["ir", "qir"], so a wrong value is rejected before any tool body runs. OpenQASM text is not a supported input. FlagQuantum ships emitters but no QASM parser, so there is nothing to convert it with; a caller holding OpenQASM has to load it into FlagQuantum itself and send the resulting IR.

Limits

Every bound is overridable by environment variable, so a deployment can tighten them without a code change:

Errors

There are two layers, and which one answers depends on whether the schema could describe the mistake.

Schema violations are caught by the MCP layer before any tool body runs and come back as a protocol error. That covers a circuit_format outside the enum, a missing required argument, and an argument of the wrong JSON type.

Everything else comes back as a structured envelope, so a caller can branch on the code instead of parsing prose:

{"status": "error", "error": {"code": "LIMIT_EXCEEDED", "message": "..."}}

Codes: INVALID_INPUT, LIMIT_EXCEEDED, UNSUPPORTED_FORMAT, SDK_UNAVAILABLE, INTERNAL_ERROR.

Both layers reach the client as an error it can read; only the layer differs. Nothing escapes as an unhandled exception that would break the transport — a failed call leaves the session usable for the next one, which tests/test_server_process.py asserts over a real stdio connection.

What this server deliberately does not do

• No execution. Nothing runs a circuit, locally or remotely. Planning is plan_execution_tool; running is the caller's step, through fq.run.
• No hardware, no credentials, no network. FlagQuantum's own release 0.2.0 ships no remote-submission entry point, and this adapter adds none.
• No noise models. A NoiseModel is a live SDK object rather than a serializable value, and every tool here takes and returns JSON.
• No in-tree coupling. This package must never be imported by the FlagQuantum repository. That project's long-horizon architecture contract names "the main repository has no production MCP transport dependency" as a retirement condition, and its tests/team/services/test_service_boundaries.py fails if mcp or fastmcp becomes importable on the core path. Keeping the gateway out of tree is what that contract asks for.

Which contracts this rests on

FlagQuantum publishes a frozen stable_exports snapshot (34 names, each with a named verification test), describes flagquantum.compiler as its "stable expert compiler interface", and lets each package declare its own __all__. This server uses all three tiers, and tests/test_api_contract.py pins the members of each:

Tier 3 is the weakest, and it is not decoration. Gate validation needs each gate's wire count and parameter names, and the SDK's operator manifest is the only authority for that — a caller cannot infer it from the circuit format, and reimplementing it here would create a second source of truth that drifts. The manifest is reached through a helper that turns a relocation into a named error rather than an AttributeError inside a tool call, and every tier-3 name is pinned by a test so a move upstream fails the build instead of failing a user. The failures that guard against are quiet ones: a weaker gate check accepts a misspelled parameter and drops it.

The dependency is pinned to flagquantum>=0.2,<0.3. It is a version range, never a git URL: a URL in the dependency table makes every environment that installs a different upstream revision unresolvable.

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/mypy --config-file ../mypy.ini src
.venv/bin/pytest -m "not integration"

See the repository README and CONTRIBUTING.md.

License

Apache-2.0.