FlagQuantum MCP Server

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 — and run them locally — with no credentials, no outbound network access and no hardware submission.

"Outbound" is the load-bearing word. Every tool here runs in this process and reaches nothing; the server never calls a provider, reads a token or submits a job. It can also *listen*, so a gateway that connects to its clients rather than launching them can reach it — see Serving over HTTP. An inbound listener is not egress.

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

Twenty-seven tools over stdio or Streamable HTTP. The research tools use the installed FlagQuantum service contract directly; the MCP layer does not reimplement request decoding, estimation, provider routing or scientific validation.

Build and inspect

Parameters

Compile and route

Export and present

Run

Research capability workflow

Four concrete resources include flagquantum://version, flagquantum://gate-set, flagquantum://ir-schema, and the installed research catalog at flagquantum://capabilities/index. Two resource templates expose exact upstream documents without copying them: flagquantum://capabilities/{capability_id}/{version} and flagquantum://schemas/{schema_id}.

Three prompts: build_and_analyze_circuit, compile_for_topology, export_circuit.

These are recipes for the clients that present them to a person — Claude Desktop, the MCP Inspector, a host that turns them into slash commands. An autonomous agent may receive none of them: several recorded sessions could not enumerate them at all, and reported that they could not tell whether prompts existed. So nothing an agent has to know lives only here. Every constraint the prompts state is also in a tool summary, or in the server instructions, or in a resource — the QCIS refusal and the "say what you assumed" rule were the two exceptions, and they are in emit_qcis_tool and bind_parameters_tool now. PROMPT_CONSTRAINTS in tests/test_server_contract.py keeps that true.

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

Serving over HTTP

A client that launches a process — Claude Code, Claude Desktop, the Inspector — uses the default stdio transport and needs nothing below. A client that instead *connects* to servers, such as a gateway holding several of them, needs the server to listen:

flagquantum-mcp-server --transport http --host 0.0.0.0 --port 8105 \

--allowed-host quantum-mcp:8105

The endpoint is /mcp on that host and port, and it speaks Streamable HTTP.

Binding a non-loopback interface requires `--allowed-host`. Without it the server refuses to start rather than listen on every interface with nothing checking who reaches it:

$ flagquantum-mcp-server --transport http --host 0.0.0.0

usage: flagquantum-mcp-server [-h] ... flagquantum-mcp-server: error: --host 0.0.0.0 is not a loopback address, so the server would answer any Host header that reaches it. Name the hosts it should answer with --allowed-host HOST[:PORT], or bind 127.0.0.1.

Passing any --allowed-host or --allowed-origin turns host validation on; a request carrying an unlisted Host is answered 421 Misdirected Request. Loopback hosts are always answered, so enabling validation cannot lock out a local client.

Two things worth knowing if you are wiring this up:

• Configure validation through the settings object, not `http_app( allowed_hosts=...)`. That keyword appends to a list which is only consulted once validation is on, so on its own it reads as a security setting and enforces nothing. Measured on fastmcp 3.4.7: a bogus Host is answered 200 with the keyword and 421 through the settings path.
• `--transport http` adds an inbound socket, not an outbound one. No tool gains a network path; rule 4 in AGENTS.md is unchanged.

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]}]

A gate carries its arguments under `parameters`, which the example above never shows because neither gate takes one:

[{"name": "rz", "index": [0], "parameters": {"theta": 0.5}}]

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.

One more naming trap: an IR payload's version field is spelled `version`, and sending ir_version instead is rejected as an unknown key — but tool results report that same field as ir_version. The payload key and the reported key are not spelled the same way.

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.

On parameters

A gate parameter is either a number or a symbol, and a symbol is written as a one-key object naming it:

{"name": "ry", "index": [0], "parameters": {"theta": {"$parameter": "theta"}}}

This works in both input formats. A symbol is what makes a circuit an ansatz: inspect_parameters_tool reports it, and bind_parameters_tool substitutes a number for it.

A bare string is not a symbol. {"theta": "theta"} is a value, not a reference; the SDK stores it as one, so the circuit reports itself as unparameterized. Nothing else complains: draw_circuit_tool prints the value it was handed, and a string prints as RY(theta) — indistinguishable from a real symbol — while plan_execution_tool plans the circuit for execution. So the input boundary rejects it, along with a misspelled marker ({"$unknown": ...}) and a non-string symbol name, naming the gate and the parameter. The other encodings a parameter may carry are $expression, $complex and $tensor; a mapping carrying none of those four keys is rejected for the same reason. The flagquantum://ir-schema resource carries a worked parameter_example.

One rough edge, inherited from the SDK: a *real* symbol is rendered as the SDK's repr of it, so RY(theta) appears as RY(Parameter(name='theta')). FlagQu