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.
MCP server for Quantinuum Nexus, wrapping the qnexus SDK. Not affiliated with Quantinuum.
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.
qnexus-mcpnever 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):
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.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Qnexus?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Qnexus precisa de uma chave de API?
O publicador lista estas variáveis de ambiente: QNEXUS_MCP_TOOLSETS, QNEXUS_MCP_ALLOW_SPEND, QNEXUS_MCP_ALLOW_HARDWARE, QNEXUS_MCP_ALLOW_DESTRUCTIVE, QNEXUS_MCP_MAX_CREDITS, QNEXUS_MCP_MAX_OUTCOMES, QNEXUS_MCP_MAX_SUBMISSIONS_PER_MINUTE, QNEXUS_MCP_PROJECTS.
Qual transporte Qnexus usa?
Qnexus roda localmente via stdio.
Quando Qnexus foi verificado pela última vez?
Última verificação: 2026-11-08. MCP server for Quantinuum Nexus, wrapping the qnexus SDK. Not affiliated with Quantinuum.