qhub-mcp 1.17.0

MCP server for the Kipu Quantum Hub

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).

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.

Prerequisites

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

Authentication

The 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 MCP server transparently reuses the same access token — no need to duplicate the token in your MCP client config. This is the recommended setup for local use so the token does not live in config files, and it keeps the CLI and the MCP server in sync on a single session.

Optional environment variables

• 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. The snippets below show the minimal configuration for common MCP clients. Add the environment block from Option B if you prefer passing the token inline instead of using qhubctl.

Option A — with qhubctl (recommended): run qhubctl login -t <TOKEN> once, then use the config without an env block.

Option B — inline token: add "env": { "KQH_PERSONAL_ACCESS_TOKEN": "<TOKEN>" } to the server entry.

Claude Desktop

One-click install (recommended): download qhub-mcp.mcpb from the latest release and double-click it, drag it into Claude Desktop, or install via Settings → Extensions → Advanced settings → Install Extension. Claude Desktop prompts for your personal access token on install and stores it in the OS keychain. uv must be installed on your machine — see the Prerequisites section.

Manual setup: edit claude_desktop_config.json (Settings → Developer → Edit Config) and add:

{
  "mcpServers": {
    "qhub-mcp": {
      "command": "uvx",
      "args": [
        "qhub-mcp"
      ]
    }
  }
}

Claude Code

Register the server with the CLI:

claude mcp add qhub-mcp -- uvx qhub-mcp

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

{
  "mcpServers": {
    "qhub-mcp": {
      "command": "uvx",
      "args": [
        "qhub-mcp"
      ]
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "qhub-mcp": {
      "command": "uvx",
      "args": [
        "qhub-mcp"
      ]
    }
  }
}

VS Code

Register the server with the CLI:

code --add-mcp "{\"name\":\"qhub-mcp\",\"command\":\"uvx\",\"args\":[\"qhub-mcp\"]}"

Or 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": {
        "command": "uvx",
        "args": [
          "qhub-mcp"
        ]
      }
    }
  }
}

Other MCP clients

Any MCP client that supports stdio servers can launch qhub-mcp with:

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

Remote deployment (Keycloak OAuth)

The same package runs as a remote HTTP server protected by Keycloak. Local stdio remains the default. Remote mode is opt-in via environment variables, so uvx qhub-mcp is unchanged.

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.

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.

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

Building the MCPB package

The Claude Desktop one-click installer is 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

The resulting qhub-mcp.mcpb can be double-clicked to install into Claude Desktop. See the MCPB documentation for details on the format.

Debugging

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

npx @modelcontextprotocol/inspector uvx qhub-mcp

To inspect a local checkout instead of the published package:

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

Authentication follows the same order as the server itself (see Authentication). Pass the token inline if you are not using qhubctl:

KQH_PERSONAL_ACCESS_TOKEN=<TOKEN> npx @modelcontextprotocol/inspector uvx qhub-mcp