Skip to main content

MCP server for the Kipu Quantum Hub

This project has been archived.

The maintainers of this project have marked this project as archived. No new releases are expected.

Project description

qhub-mcp

MCP server for the Kipu Quantum Hub. Exposes the Hub and Quantum Workloads APIs as tools for MCP-compatible agents and editors (Claude Desktop, Claude Code, Cursor, VS Code, and any other MCP client).

The recommended way to use it is the hosted remote server at https://api.hub.kipu-quantum.com/mcp. No local install and no personal access token are needed: the client authenticates through a browser-based OAuth flow. The local stdio package on PyPI (uvx qhub-mcp) is deprecated — see Deprecated: local stdio install.

What it provides

Tools are grouped into two namespaces:

  • hub_* — core Hub platform API (services, data pools, applications, use cases, ...)
  • quantum_* — Quantum Workloads API (quantum jobs, sessions, backends, ...)

Plus a top-level run_subscribed_service tool to invoke services you are subscribed to.

Connecting to the hosted server (recommended)

The Hub runs a hosted remote server at https://api.hub.kipu-quantum.com/mcp. Connecting to it needs no local install and no personal access token: the client authenticates through a browser-based OAuth flow, and the server forwards your verified token to the Hub API.

The remote server speaks the streamable-HTTP transport, so it is added as a remote server / custom connector, not as a launched command.

The URL must include the /mcp path and carry no trailing slash, so it matches the resource the server advertises.

Claude Code

claude mcp add --transport http qhub-mcp https://api.hub.kipu-quantum.com/mcp

Or add it to .mcp.json / ~/.claude.json:

{
  "mcpServers": {
    "qhub-mcp": {
      "type": "http",
      "url": "https://api.hub.kipu-quantum.com/mcp"
    }
  }
}

The first tool call opens a browser to authenticate; the session is cached afterwards.

Claude Desktop

Settings → Connectors → Add custom connector, then enter:

  • Name: qhub-mcp
  • URL: https://api.hub.kipu-quantum.com/mcp

Claude Desktop runs the OAuth flow in a popup on first use.

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "qhub-mcp": {
      "type": "http",
      "url": "https://api.hub.kipu-quantum.com/mcp"
    }
  }
}

VS Code

Add to your user or workspace settings.json (requires an MCP-capable extension such as GitHub Copilot Chat in agent mode):

{
  "mcp": {
    "servers": {
      "qhub-mcp": {
        "type": "http",
        "url": "https://api.hub.kipu-quantum.com/mcp"
      }
    }
  }
}

Other MCP clients

Any client that supports remote (streamable-HTTP) MCP servers connects with:

  • transport: http (streamable HTTP)
  • URL: https://api.hub.kipu-quantum.com/mcp

Clients that only support stdio can bridge to the remote server with a proxy such as mcp-remote:

npx mcp-remote https://api.hub.kipu-quantum.com/mcp

Account scope

Each tool accepts an optional organization parameter (the x-OrganizationId header parameter). Omit it to act on the user's personal account, or pass an organization UUID to act within that organization. Use hub_getMyAccounts or hub_getOrganizations to discover available organizations.

Deprecated: local stdio install (PyPI)

Deprecated. The local stdio package (uvx qhub-mcp) is retired in favor of the hosted remote server. It is kept only for existing setups, offline use, or pointing at a non-default Hub via QHUB_API_BASE_URL. New users should connect to the hosted server instead.

Prerequisites

  • Python >= 3.12
  • uv (provides uvx)
  • A Kipu Quantum Hub personal access token

Authentication

The local server picks up credentials in the following order:

  1. KQH_PERSONAL_ACCESS_TOKEN environment variable.
  2. Credentials stored by qhubctl after qhubctl login -t <YOUR_PERSONAL_ACCESS_TOKEN>.

When you authenticate with qhubctl, the server transparently reuses the same access token, so the token does not live in config files.

Optional environment variable:

  • QHUB_API_BASE_URL — override the API base URL (defaults to https://api.hub.kipu-quantum.com). Useful for staging or self-hosted Hubs.

Configuration

The server is launched via uvx qhub-mcp. Any stdio-capable MCP client uses:

  • command: uvx
  • args: ["qhub-mcp"]
  • optional env: { "KQH_PERSONAL_ACCESS_TOKEN": "<TOKEN>", "QHUB_API_BASE_URL": "<URL>" }

For example, in .mcp.json / claude_desktop_config.json / ~/.cursor/mcp.json:

{
  "mcpServers": {
    "qhub-mcp": {
      "command": "uvx",
      "args": [
        "qhub-mcp"
      ],
      "env": {
        "KQH_PERSONAL_ACCESS_TOKEN": "<TOKEN>"
      }
    }
  }
}

Omit the env block when authenticating with qhubctl.

Local MCPB bundle

A Claude Desktop one-click installer for the local stdio server was shipped as an .mcpb file built from mcpb/manifest.json. To rebuild it locally:

npm install -g @anthropic-ai/mcpb
mcpb pack ./mcpb qhub-mcp.mcpb

# or with npx:
npx @anthropic-ai/mcpb pack ./mcpb qhub-mcp.mcpb

See the MCPB documentation for details on the format.

Remote deployment (Keycloak OAuth)

This section is for operators self-hosting the remote server (the same deployment that powers the hosted endpoint above). The same package runs as a remote HTTP server protected by Keycloak. Remote mode is opt-in via environment variables.

Server environment variables

Variable Required Description
QHUB_MCP_TRANSPORT yes (http) Set to http to enable remote mode. Defaults to stdio.
KEYCLOAK_REALM_URL yes (remote) Keycloak realm URL, e.g. https://auth.example.com/realms/kipu.
MCP_PUBLIC_URL yes (remote) The externally reachable URL of this server, including the /mcp mount prefix, e.g. https://mcp.hub.kipu-quantum.com/mcp. Must match what clients connect to. The MCP endpoint and the operational OAuth endpoints are served under /mcp; only the OAuth discovery (/.well-known/*) endpoints stay at the host root, as required by RFC 8414 / RFC 9728.
MCP_AUDIENCE no Expected token audience to validate (recommended).
KEYCLOAK_CLIENT_ID yes (remote) Client ID of the pre-registered static Keycloak client (e.g. qhub-mcp).
JWT_SIGNING_KEY required when QHUB_MCP_REDIS_URL is set Stable secret signing the server's reference tokens. Must not change across restarts or replicas, or clients are forced to re-authenticate. When both this and QHUB_MCP_REDIS_URL are unset, an ephemeral key is generated for local use.
QHUB_MCP_REDIS_URL production Redis URL backing OAuth state and per-session tokens, e.g. rediss://redis:6380/0. Required for stateless/multi-replica deployment. Omit for local runs to use the built-in encrypted file store.
QHUB_MCP_HOST no Bind host (default 0.0.0.0).
QHUB_MCP_PORT no Bind port (default 8000).

Keycloak client setup

Pre-register one static OAuth client in the realm (no Dynamic Client Registration needed). Create a client qhub-mcp with:

  • Client authentication: off (public client).
  • Standard flow: on (authorization code).
  • PKCE method: S256.
  • Valid redirect URI: <MCP_PUBLIC_URL>/auth/callback (e.g. https://mcp.hub.kipu-quantum.com/mcp/auth/callback, since MCP_PUBLIC_URL includes the /mcp prefix).

The server proxies the OAuth flow to Keycloak through this single client, so the realm holds one client regardless of how many users connect.

Running

QHUB_MCP_TRANSPORT=http \
KEYCLOAK_REALM_URL="https://auth.example.com/realms/kipu" \
MCP_PUBLIC_URL="https://mcp.hub.kipu-quantum.com/mcp" \
MCP_AUDIENCE="qhub-mcp" \
KEYCLOAK_CLIENT_ID="qhub-mcp" \
JWT_SIGNING_KEY="<a-stable-random-secret>" \
QHUB_MCP_REDIS_URL="rediss://redis:6380/0" \
uvx qhub-mcp

Or with Docker:

docker build -t qhub-mcp:remote .
docker run --rm -p 8000:8000 \
  -e KEYCLOAK_REALM_URL="https://auth.example.com/realms/kipu" \
  -e MCP_PUBLIC_URL="https://mcp.hub.kipu-quantum.com/mcp" \
  qhub-mcp:remote

Deploy behind TLS so the public URL is https://… and matches MCP_PUBLIC_URL. The server advertises its protected-resource metadata at /.well-known/oauth-protected-resource/mcp and its authorization-server metadata at /.well-known/oauth-authorization-server/mcp — both at the host root (not under /mcp), as RFC 8414 / RFC 9728 require.

Authentication and account scope

Clients authenticate to the server via the Keycloak OAuth flow. The server forwards the caller's verified token to the Kipu Hub API as a Bearer token, so no personal access token is needed in remote mode.

Local development

  1. Clone this repository.
  2. Install uv if you don't have it.
  3. Run uv sync.
  4. Point your MCP client at the local checkout:
    {
      "mcpServers": {
        "qhub-mcp": {
          "command": "uv",
          "args": [
            "--directory",
            "<PROJECT_PATH>",
            "run",
            "src/qhub_mcp/server.py"
          ],
          "env": {
            "KQH_PERSONAL_ACCESS_TOKEN": "<YOUR_PERSONAL_ACCESS_TOKEN>"
          }
        }
      }
    }
    

Debugging

Use the MCP Inspector to interactively explore the server's tools, inspect requests and responses, and troubleshoot issues.

Against the hosted remote server:

npx @modelcontextprotocol/inspector

Then connect the Inspector to https://api.hub.kipu-quantum.com/mcp over the streamable-HTTP transport and complete the OAuth flow.

Against a local checkout:

npx @modelcontextprotocol/inspector uv --directory <PROJECT_PATH> run src/qhub_mcp/server.py

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

qhub_mcp-1.19.0.tar.gz (109.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

qhub_mcp-1.19.0-py3-none-any.whl (22.2 kB view details)

Uploaded Python 3

File details

Details for the file qhub_mcp-1.19.0.tar.gz.

File metadata

  • Download URL: qhub_mcp-1.19.0.tar.gz
  • Upload date:
  • Size: 109.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.9.30 {"installer":{"name":"uv","version":"0.9.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for qhub_mcp-1.19.0.tar.gz
Algorithm Hash digest
SHA256 74de5602fd093e90dfdd0e5cb21e91250f7f64476da5cea8afeba23b540db456
MD5 0cff1a3545a5d3fbdbaa05442e3ed3ff
BLAKE2b-256 ada95288578d9dae0fca5e04a9d94673be7f159043f3e754aab2b61db555891a

See more details on using hashes here.

File details

Details for the file qhub_mcp-1.19.0-py3-none-any.whl.

File metadata

  • Download URL: qhub_mcp-1.19.0-py3-none-any.whl
  • Upload date:
  • Size: 22.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.9.30 {"installer":{"name":"uv","version":"0.9.30","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"12","id":"bookworm","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for qhub_mcp-1.19.0-py3-none-any.whl
Algorithm Hash digest
SHA256 e1b7015b0e3a52086da88ca95758af8c0d843a07ca4dc384d204102e0d82dea3
MD5 86b6bc64be6046092101820960d98f4c
BLAKE2b-256 eb008c8c31f5a029b6fba7a8fb83d45e3c4fbd89831b6551b2c9f1dcd66f25be

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page