qhub-mcp 1.19.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).

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