qnexus-mcp

qnexus-mcp

A community Model Context Protocol (MCP) server for Quantinuum Nexus, wrapping the official qnexus Python SDK so any MCP-speaking agent (Claude Code, Cursor, VS Code, Codex, …) can inspect Nexus and, opt-in, run circuits on the free emulator.

Not affiliated with, endorsed by, or an official product of Quantinuum. "Quantinuum" and "Nexus" are trademarks of their respective owners, used here nominatively to describe compatibility.

Status

Early development. Read-only by default. Design and rationale live in docs/DESIGN.md; the research behind it is in docs/research/.

Requirements

• Python 3.10+ and uv (the uvx command). On Windows, note the full path to uvx.exe (where uvx in a terminal) — GUI clients don't inherit your shell PATH.
• A Quantinuum Nexus account.

1. Authenticate (once)

qnexus-mcp never handles your Nexus token. Authenticate out-of-band with the qnexus CLI (it opens your browser):

uvx --from qnexus qnx login

Inside Nexus JupyterHub, authentication is automatic; do not run qnx login there.

2. Add the server to your MCP client

The launch command is the same everywhere — only the config file differs per client:

uvx qnexus-mcp==0.2.0                              # read-only (default)
uvx qnexus-mcp==0.2.0 --toolsets read,execute      # + run circuits on the free H2-1LE emulator

Pin a version (==0.2.0): uvx otherwise resolves the latest PyPI release on every launch — unpinned installs are neither reproducible nor auditable. Avoid 0.1.0 on Windows: its first tool call hangs (fixed in 0.2.0).

What to expect on startup: the first ever launch downloads the quantum SDK stack (1–3 min); every launch takes ~30 s before the server responds — the SDK is imported up front, before the MCP handshake. "Waiting for server to respond to initialize" during that window is normal.

Claude Desktop

Settings → Developer → Local MCP servers → Edit Config (always use this button — the Microsoft Store build keeps the file under %LOCALAPPDATA%\Packages\Claude_*\..., not %APPDATA%\Claude), then add:

{
  "mcpServers": {
    "nexus": {
      "command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe", // or plain "uvx" on macOS/Linux
      "args": ["qnexus-mcp==0.2.0", "--toolsets", "read,execute"]
    }
  }
}

Then quit Claude Desktop fully and reopen — the config is only read at cold start, and closing the window leaves the old process running (tray icon → Quit, or taskkill /F /IM claude.exe).

VS Code

Command Palette → MCP: Open User Configuration (or a workspace .vscode/mcp.json):

{
  "servers": {
    "nexus": {
      "type": "stdio",
      "command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe", // or plain "uvx" on macOS/Linux
      "args": ["qnexus-mcp==0.2.0", "--toolsets", "read,execute"]
    }
  }
}

Claude Code

claude mcp add nexus -- uvx qnexus-mcp==0.2.0 --toolsets read,execute

Other MCP clients (Cursor, Codex, …)

Same command; the config shape is one of the two JSON forms above (mcpServers vs servers + "type": "stdio") — check your client's docs for which file to put it in.

Something not working? See docs/TROUBLESHOOTING.md — it covers every failure mode observed in real client setups (wrong config path, slow first start, auth, rate limits, known Nexus-side errors).

Configuration

Flag	Env	Default	Effect
--toolsets	QNEXUS_MCP_TOOLSETS	read	Capability domains to expose (read,execute,manage,destructive)
--allow-spend	QNEXUS_MCP_ALLOW_SPEND	false	Permit credit-spending (HQC) execution
--allow-hardware	QNEXUS_MCP_ALLOW_HARDWARE	false	Permit real-QPU targets
--allow-destructive	QNEXUS_MCP_ALLOW_DESTRUCTIVE	false	Permit delete/cancel/archive
--max-credits	QNEXUS_MCP_MAX_CREDITS	0	Hard per-call HQC ceiling; 0 blocks all spend
--max-outcomes	QNEXUS_MCP_MAX_OUTCOMES	100	Top-N cap on distinct measurement outcomes returned per result (truncation is always reported)
--max-submissions-per-minute	QNEXUS_MCP_MAX_SUBMISSIONS_PER_MINUTE	6	Sliding-window submission cap; each circuit in a batch counts as one
--projects	QNEXUS_MCP_PROJECTS	(all)	Comma-separated project allowlist, enforced on every mutating tool

Safety

Read-only by default. Anything that spends credits or mutates cloud state requires an explicit opt-in flag and an in-protocol confirmation, and the default execution backend is the free, noiseless H2-1LE emulator. Submissions are rate-limited, cloud mutations are serialized, destructive project operations resolve their target by exact name (never substring), and the server never reads, stores, or returns your Nexus token. Every control is enforced server-side; MCP tool annotations are treated as UX hints only. See docs/DESIGN.md §6–§7.

Prompt injection (conscious design decision). Everything Nexus returns — job names, project names, error messages, results — is attacker-influencable content (any Nexus user can name a job) and is treated as untrusted data. There is no structural tagging that separates "data" from "instructions" in today's MCP ecosystem; the structural boundary here is instead that injected content cannot escalate: every action with consequences (spending credits, targeting hardware, deleting anything) requires launch flags the agent cannot set plus an in-protocol human confirmation naming the exact target and cost. Injected text can at worst confuse the agent's reasoning — it cannot spend or destroy anything on its own. This residual risk is accepted and documented, not an omission.

Governance. This is an early-stage, single-maintainer project (see CODEOWNERS): releases are published by one person via GitHub-OIDC Trusted Publishing (no long-lived PyPI tokens). Pin a version (above) if that trust model matters for your deployment.

Contributing

See CONTRIBUTING.md. Contributions are accepted under the Developer Certificate of Origin; sign off your commits with -s.

License

Apache-2.0. See LICENSE and NOTICE.