{
  "markdown": "# qnexus-mcp\n\nA community [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for **Quantinuum Nexus**,\nwrapping the official [`qnexus`](https://github.com/Quantinuum/qnexus) Python SDK so any MCP-speaking agent\n(Claude Code, Cursor, VS Code, Codex, …) can inspect Nexus and, opt-in, run circuits on the free emulator.\n\n> **Not affiliated with, endorsed by, or an official product of Quantinuum.** \"Quantinuum\" and \"Nexus\" are\n> trademarks of their respective owners, used here nominatively to describe compatibility.\n\n<!-- mcp-name: io.github.Blite-HQ/qnexus-mcp -->\n\n## Status\n\nEarly development. **Read-only by default.** Design and rationale live in\n[`docs/DESIGN.md`](docs/DESIGN.md); the research behind it is in [`docs/research/`](docs/research/).\n\n## Requirements\n\n- Python 3.10+ and [`uv`](https://docs.astral.sh/uv/) (the `uvx` command). On Windows, note the\n  full path to `uvx.exe` (`where uvx` in a terminal) — GUI clients don't inherit your shell PATH.\n- A [Quantinuum Nexus](https://nexus.quantinuum.com) account.\n\n## 1. Authenticate (once)\n\n`qnexus-mcp` **never handles your Nexus token.** Authenticate out-of-band with the `qnexus` CLI\n(it opens your browser):\n\n```bash\nuvx --from qnexus qnx login\n```\n\nInside Nexus JupyterHub, authentication is automatic; do not run `qnx login` there.\n\n## 2. Add the server to your MCP client\n\nThe launch command is the same everywhere — only the config file differs per client:\n\n```\nuvx qnexus-mcp==0.2.0                              # read-only (default)\nuvx qnexus-mcp==0.2.0 --toolsets read,execute      # + run circuits on the free H2-1LE emulator\n```\n\n**Pin a version** (`==0.2.0`): `uvx` otherwise resolves the latest PyPI release on every launch —\nunpinned installs are neither reproducible nor auditable. Avoid `0.1.0` on Windows: its first\ntool call hangs (fixed in 0.2.0).\n\n> **What to expect on startup:** the first ever launch downloads the quantum SDK stack (1–3 min);\n> every launch takes ~30 s before the server responds — the SDK is imported up front, before the\n> MCP handshake. \"Waiting for server to respond to `initialize`\" during that window is normal.\n\n### Claude Desktop\n\nSettings → Developer → Local MCP servers → **Edit Config** (always use this button — the\nMicrosoft Store build keeps the file under `%LOCALAPPDATA%\\Packages\\Claude_*\\...`, **not**\n`%APPDATA%\\Claude`), then add:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"nexus\": {\n      \"command\": \"C:\\\\Users\\\\<you>\\\\.local\\\\bin\\\\uvx.exe\", // or plain \"uvx\" on macOS/Linux\n      \"args\": [\"qnexus-mcp==0.2.0\", \"--toolsets\", \"read,execute\"]\n    }\n  }\n}\n```\n\nThen **quit Claude Desktop fully and reopen** — the config is only read at cold start, and\nclosing the window leaves the old process running (tray icon → Quit, or\n`taskkill /F /IM claude.exe`).\n\n### VS Code\n\nCommand Palette → `MCP: Open User Configuration` (or a workspace `.vscode/mcp.json`):\n\n```jsonc\n{\n  \"servers\": {\n    \"nexus\": {\n      \"type\": \"stdio\",\n      \"command\": \"C:\\\\Users\\\\<you>\\\\.local\\\\bin\\\\uvx.exe\", // or plain \"uvx\" on macOS/Linux\n      \"args\": [\"qnexus-mcp==0.2.0\", \"--toolsets\", \"read,execute\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add nexus -- uvx qnexus-mcp==0.2.0 --toolsets read,execute\n```\n\n### Other MCP clients (Cursor, Codex, …)\n\nSame command; the config shape is one of the two JSON forms above (`mcpServers` vs\n`servers` + `\"type\": \"stdio\"`) — check your client's docs for which file to put it in.\n\nSomething not working? See [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — it covers every\nfailure mode observed in real client setups (wrong config path, slow first start, auth, rate\nlimits, known Nexus-side errors).\n\n## Configuration\n\n| Flag | Env | Default | Effect |\n|---|---|---|---|\n| `--toolsets` | `QNEXUS_MCP_TOOLSETS` | `read` | Capability domains to expose (`read,execute,manage,destructive`) |\n| `--allow-spend` | `QNEXUS_MCP_ALLOW_SPEND` | `false` | Permit credit-spending (HQC) execution |\n| `--allow-hardware` | `QNEXUS_MCP_ALLOW_HARDWARE` | `false` | Permit real-QPU targets |\n| `--allow-destructive` | `QNEXUS_MCP_ALLOW_DESTRUCTIVE` | `false` | Permit delete/cancel/archive |\n| `--max-credits` | `QNEXUS_MCP_MAX_CREDITS` | `0` | Hard per-call HQC ceiling; `0` blocks all spend |\n| `--max-outcomes` | `QNEXUS_MCP_MAX_OUTCOMES` | `100` | Top-N cap on distinct measurement outcomes returned per result (truncation is always reported) |\n| `--max-submissions-per-minute` | `QNEXUS_MCP_MAX_SUBMISSIONS_PER_MINUTE` | `6` | Sliding-window submission cap; each circuit in a batch counts as one |\n| `--projects` | `QNEXUS_MCP_PROJECTS` | *(all)* | Comma-separated project allowlist, enforced on every mutating tool |\n\n## Safety\n\nRead-only by default. Anything that spends credits or mutates cloud state requires an explicit opt-in flag\n**and** an in-protocol confirmation, and the default execution backend is the free, noiseless `H2-1LE`\nemulator. Submissions are rate-limited, cloud mutations are serialized, destructive project operations\nresolve their target by **exact** name (never substring), and the server never reads, stores, or returns\nyour Nexus token. Every control is enforced server-side; MCP tool annotations are treated as UX hints\nonly. See [`docs/DESIGN.md`](docs/DESIGN.md) §6–§7.\n\n**Prompt injection (conscious design decision).** Everything Nexus returns — job names, project names,\nerror messages, results — is attacker-influencable content (any Nexus user can name a job) and is treated\nas untrusted data. There is no structural tagging that separates \"data\" from \"instructions\" in today's MCP\necosystem; the structural boundary here is instead that **injected content cannot escalate**: every action\nwith consequences (spending credits, targeting hardware, deleting anything) requires launch flags the\nagent cannot set *plus* an in-protocol human confirmation naming the exact target and cost. Injected text\ncan at worst confuse the agent's reasoning — it cannot spend or destroy anything on its own. This residual\nrisk is accepted and documented, not an omission.\n\n**Governance.** This is an early-stage, single-maintainer project (see `CODEOWNERS`): releases are\npublished by one person via GitHub-OIDC Trusted Publishing (no long-lived PyPI tokens). Pin a version\n(above) if that trust model matters for your deployment.\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md). Contributions are accepted under the\n[Developer Certificate of Origin](https://developercertificate.org/); sign off your commits with `-s`.\n\n## License\n\nApache-2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).\n",
  "bytes": 6582,
  "sha": "8f3f5b3491e35ac7ba987aaf7bf541b4a9f62d6eafc845d3b75789f5b7a8825f",
  "repo_slug": "blite-hq/qnexus-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_blite_hq_qnexus_mcp_37ccb922/readme"
}