Quantum Hub Controls Hands-On: One Service Through the CLI, SDK and MCP

Educational disclaimer. The antenna district is invented with a fixed seed and stands for no real network. CLI output, statuses, timings and printed values are snapshots from 24 to 29 September 2026, last run with qhubctl 2.2.4, and they will drift. The CLI's own --help and the linked Hub docs are the single source of truth.

In this lab we slip into the role of a developer who ships a quantum-centric workflow as a Hub service. You already have an optimization algorithm that returns solutions on your laptop. So how do you serve that on the Hub without falling into its pitfalls, and without silent errors? We carry this one small service through the Hub's three controls: the qhubctl CLI to build and deploy, the qhub-api SDK to control, and the qhub-mcp server to make the service available for agents. Everything runs on a free Hub account.

You need: Sessions 1 to 3 (your first entangled circuit, the optimization lab, the machine learning lab), a free Hub account, uv with Python 3.11 or newer, Node.js 20 or newer, and qhubctl 2.2.4.

Step 5 is optional and needs an agent that can call the Hub's tools. Either request access to Paqari, Kipu's hosted agent, from the Kipu Academy team, or connect your own assistant to the Hub MCP server (see the MCP server docs).

The lab runs in three phases: build the service (Steps 1 and 2), test it locally (Step 3), then deploy it and read it back (Steps 4 and 5). Step 6 chains it with a second service in a workflow. Every task carries collapsed hints: Hint 1 says where to look, Hint 2 shows the shape of the answer, and the Solution closes it.

0Step 0: Set up the environment

npm install -g @quantum-hub/qhubctl
qhubctl --version
qhubctl login -t <your personal access token>
qhubctl list-contexts
qhubctl set-context <the id of your own personal account>
qhubctl get-context
export KQH_PERSONAL_ACCESS_TOKEN=<your personal access token>

1Step 1: What does run() receive?

About 8 minutes.

qhubctl init writes a complete, deployable Python service. Before you change anything, find out how the Hub hands your code its input. Work in a folder of your own:

qhubctl init --name t4-antenna-greedy --non-interactive
cd t4-antenna-greedy

You should see a new folder that holds, among others, src/, input/ and qhub.json.

Three files matter in this lab. src/program.py holds InputData, InputParams and run(), the function the Hub calls. src/__main__.py is the local runner: python -m src calls run() on the files in input/ and writes to out/. qhub.json names the service and its runtime. init also writes .claude/skills/ with three Claude Code skills, among them kqh-service-builder on service structure, run() conventions, local testing and deployment, and a .mcp.json that registers the qhub-mcp server for Claude Code. The init reference and the runtime interface cover the rest.

What do you think is happening here?

2Step 2: Does the service reach a solution on your laptop?

About 20 minutes.

The problem is antenna siting. There are 12 candidate sites, and each has a net value. Some pairs of sites overlap in coverage, and a pair costs a penalty when both are chosen. Three pairs are excluded outright. The goal is to maximise the total net value minus the overlap penalties. The solver is a classical greedy, because the lab is about the controls around it.

Paste the district and the lab's service over the starter: the three files below replace the starter's input/data.json, input/params.json and src/program.py.

{"net_value": [29, 17, 22, 0, 12, 37, 14, 16, 34, 12, 24, 20], "overlap": {"0,4": 23, "0,7": 9, "0,8": 9, "1,3": 23, "1,7": 6, "2,6": 10, "2,8": 23, "3,6": 21, "3,9": 20, "4,5": 22, "5,11": 14, "6,10": 17, "8,10": 14, "8,11": 12}, "exclusions": [[0, 3], [2, 7], [5, 9]]}

{}

import time
from typing import Dict, List

from loguru import logger
from pydantic import BaseModel, Field


class InputData(BaseModel):
    """The antenna district, read from the `data` key of the job input.

    net_value:  one value per candidate site, indexed 0..n-1.
    overlap:    pairwise penalty keyed "i,j" with i < j, paid when both sites are chosen.
    exclusions: pairs [i, j] that must never both be chosen.
    """

    net_value: List[float] = Field(default_factory=list)
    overlap: Dict[str, float] = Field(default_factory=dict)
    exclusions: List[List[int]] = Field(default_factory=list)


class InputParams(BaseModel):
    """Read from the `params` key of the job input. Empty in this lab."""

    pass


class CalculationResult(BaseModel):
    chosen_sites: List[int]
    objective: float
    elapsed_time: float


def _parse_overlap(overlap: Dict[str, float]) -> Dict[tuple, float]:
    """Turn {"i,j": w} into {(i, j): w} with integer keys."""
    return {tuple(sorted(int(x) for x in k.split(","))): w for k, w in overlap.items()}


def _objective(chosen: set, net_value: List[float], overlap: Dict[tuple, float]) -> float:
    """Sum of net_value over chosen sites, minus w for every overlap pair with both sites chosen."""
    penalty = sum(w for (i, j), w in overlap.items() if i in chosen and j in chosen)
    return sum(net_value[i] for i in chosen) - penalty


def _feasible(i: int, chosen: set, exclusions: List[List[int]]) -> bool:
    """False if site i forms an excluded pair with any site already chosen."""
    return not any((a == i and b in chosen) or (b == i and a in chosen) for a, b in exclusions)


def run(data: InputData, params: InputParams) -> CalculationResult:
    """Best-gain greedy for antenna siting.

    Start with no sites. At each step add the feasible site with the largest
    positive marginal gain to sum(net_value_i x_i) - sum(w_ij x_i x_j), never
    selecting both sites of an excluded pair. Stop when no remaining site has
    a positive gain.
    """
    start_time = time.time()
    chosen: set = set()
    obj = 0.0

    overlap = _parse_overlap(data.overlap)
    while True:
        best_gain, best_i = 0.0, None
        for i in range(len(data.net_value)):
            if i in chosen or not _feasible(i, chosen, data.exclusions):
                continue
            gain = data.net_value[i] - sum(
                overlap.get((min(i, j), max(i, j)), 0.0) for j in chosen
            )
            if gain > best_gain:
                best_gain, best_i = gain, i
        if best_i is None:
            break
        chosen.add(best_i)
    obj = _objective(chosen, data.net_value, overlap)

    elapsed_time = time.time() - start_time
    logger.debug(f"Chosen sites: {sorted(chosen)}, objective: {obj}")

    return CalculationResult(
        chosen_sites=sorted(chosen),
        objective=obj,
        elapsed_time=elapsed_time,
    )

The greedy is written: it starts with no sites, adds the feasible site with the largest positive gain, and stops when no site adds value. The docstring of run() states it. Your job in this lab is to run it, first on your laptop, then on the Hub.

uv run python -m src

You should see this in out/output.json:

"chosen_sites": [0, 1, 5, 6, 7, 8],
"objective": 123.0,

The objective is 123. It is a good plan, but not the best one. Checking every plan by brute force finds an optimum of 135, so the greedy leaves 12 on the table. That gap does not matter until Step 6, because here the greedy is only the payload.

3Step 3: Why does the same program return 0 when served?

About 12 minutes.

qhubctl serve runs your project on your machine and, in its own words, exposes the same HTTP endpoints as Kipu Quantum Hub. Start it in one terminal and leave it running:

qhubctl serve

It listens on http://localhost:8081, and http://localhost:8081/docs lists the endpoints.

On the first start, serve runs uv add --dev --upgrade qhub-serve, which changes pyproject.toml and uv.lock. Leave those changes in place, because the Hub build copes with them. The endpoints are the Hub's: POST / starts a job, GET /<id> reads its status, and GET /<id>/result its result. Errors from your code print in the serve terminal, not in the curl response.

Before you send: what objective do you expect back? Then, from a second terminal in the project folder, send the district:

curl -s -i -X POST http://localhost:8081/ -H 'Content-Type: application/json' -d @input/data.json

The first line of the answer is HTTP/1.1 201 Created, and the body carries an id and "status":"PENDING". Wait a few seconds, then ask for the status and the result:

curl -s http://localhost:8081/<id>
curl -s http://localhost:8081/<id>/result

You should see "status":"SUCCEEDED", and a result that says "chosen_sites":[],"objective":0.0.

Same program, same district: python -m src returned 123, and serve returned 0 with no sites. What is different?

{"data": {"net_value": [29, 17, 22, 0, 12, 37, 14, 16, 34, 12, 24, 20], "overlap": {"0,4": 23, "0,7": 9, "0,8": 9, "1,3": 23, "1,7": 6, "2,6": 10, "2,8": 23, "3,6": 21, "3,9": 20, "4,5": 22, "5,11": 14, "6,10": 17, "8,10": 14, "8,11": 12}, "exclusions": [[0, 3], [2, 7], [5, 9]]}, "params": {}}

curl -s -X POST http://localhost:8081/ -H 'Content-Type: application/json' -d @input/job.json
curl -s http://localhost:8081/<id>/result

What do you think is happening here?

import time
from typing import Dict, List

from loguru import logger
from pydantic import BaseModel


class InputData(BaseModel):
    """The antenna district, read from the `data` key of the job input.

    net_value:  one value per candidate site, indexed 0..n-1.
    overlap:    pairwise penalty keyed "i,j" with i < j, paid when both sites are chosen.
    exclusions: pairs [i, j] that must never both be chosen.
    """

    net_value: List[float]
    overlap: Dict[str, float]
    exclusions: List[List[int]]


class InputParams(BaseModel):
    """Read from the `params` key of the job input. Empty in this lab."""

    pass


class CalculationResult(BaseModel):
    chosen_sites: List[int]
    objective: float
    elapsed_time: float


def _parse_overlap(overlap: Dict[str, float]) -> Dict[tuple, float]:
    """Turn {"i,j": w} into {(i, j): w} with integer keys."""
    return {tuple(sorted(int(x) for x in k.split(","))): w for k, w in overlap.items()}


def _objective(chosen: set, net_value: List[float], overlap: Dict[tuple, float]) -> float:
    """Sum of net_value over chosen sites, minus w for every overlap pair with both sites chosen."""
    penalty = sum(w for (i, j), w in overlap.items() if i in chosen and j in chosen)
    return sum(net_value[i] for i in chosen) - penalty


def _feasible(i: int, chosen: set, exclusions: List[List[int]]) -> bool:
    """False if site i forms an excluded pair with any site already chosen."""
    return not any((a == i and b in chosen) or (b == i and a in chosen) for a, b in exclusions)


def run(data: InputData, params: InputParams) -> CalculationResult:
    """Best-gain greedy for antenna siting.

    Start with no sites. At each step add the feasible site with the largest
    positive marginal gain to sum(net_value_i x_i) - sum(w_ij x_i x_j), never
    selecting both sites of an excluded pair. Stop when no remaining site has
    a positive gain.
    """
    start_time = time.time()
    chosen: set = set()
    obj = 0.0

    overlap = _parse_overlap(data.overlap)
    while True:
        best_gain, best_i = 0.0, None
        for i in range(len(data.net_value)):
            if i in chosen or not _feasible(i, chosen, data.exclusions):
                continue
            gain = data.net_value[i] - sum(
                overlap.get((min(i, j), max(i, j)), 0.0) for j in chosen
            )
            if gain > best_gain:
                best_gain, best_i = gain, i
        if best_i is None:
            break
        chosen.add(best_i)
    obj = _objective(chosen, data.net_value, overlap)

    elapsed_time = time.time() - start_time
    logger.debug(f"Chosen sites: {sorted(chosen)}, objective: {obj}")

    return CalculationResult(
        chosen_sites=sorted(chosen),
        objective=obj,
        elapsed_time=elapsed_time,
    )

ERROR | qhub_serve.entrypoint:run_entrypoint_wrapper:64 - 3 validation errors for InputData
net_value
  Field required [type=missing, input_value={}, input_type=dict]

You might expect the whole body to arrive as run()'s data. It doesn't: the Hub binds each top-level key of the body to the run() parameter of the same name, so the district goes inside a data key, the job envelope.

4Step 4: What does qhubctl run send once the service is on the Hub?

About 15 minutes.

Check the context first, every time. qhubctl deploys into whichever account it was last left in, and qhubctl has no command to delete a service. A service created in the wrong organization stays there until someone removes it by other means.

qhubctl openapi
qhubctl get-context
qhubctl up

qhubctl openapi reads the types in run() and writes openapi.yaml, and up uploads that file as the service's API description. Its POST / request body, trimmed:

properties:
  data:
    title: InputData      # after Task 3: requires net_value, overlap, exclusions
  params:
    title: InputParams
required:
- data
- params

up creates the service, uploads the project and builds it. One build takes 149 to 177 seconds, so up takes about 2.5 to 3 minutes in all. up saves the new serviceId into qhub.json, so a second up updates the same service. qhubctl up --help lists the options, and the up reference and the build logs are the first place to look if a build fails. Work on Task 4a while the build runs.

You should see Service created, and in the Hub, under Services, your service with the status "Service created".

What do you think is happening here?

qhubctl get-context
qhubctl run --input-files input/job.json --tag t4-greedy --detached

# /// script
# requires-python = ">=3.11"
# dependencies = ["qhub-api"]
# ///
import os, sys, time
from qhub.api.platform.client import HubPlatformClient

client = HubPlatformClient(api_key=os.environ["KQH_PERSONAL_ACCESS_TOKEN"])
job_id = sys.argv[1]

while (status := str(client.service_jobs.get_service_job(id=job_id).status)) not in ("SUCCEEDED", "FAILED", "CANCELLED"):
    print(status)
    time.sleep(5)

execution = client.service_executions.get_service_execution(id=job_id)
print("execution", execution.id, execution.status)
if status == "SUCCEEDED":
    result = client.service_executions.get_service_execution_result(id=job_id)
    print("objective", result["objective"], "sites", result["chosen_sites"])

cd ..
uv run readback.py <job-id>

execution <job-id> SUCCEEDED
objective 123.0 sites [0, 1, 5, 6, 7, 8]

5Step 5: Can an agent recover from the same mistake? (optional)

About 5 minutes.

An agent on the Hub MCP calls the Hub's hub_* tools for you. This time you give it a goal, not a body: the flat district, which broke serve and run, and no word about the envelope.

Before you send: what body will the agent send first, and what will it do if the job fails?

Then ask your assistant, from your service folder, or Paqari, pasting the contents of input/data.json after the prompt. If you gave your service another name in Step 1, swap it in:

Run my Hub service t4-antenna-greedy on the antenna district in input/data.json and tell me the objective, the chosen sites and the execution ID. Only run it; do not create, rebuild, publish or change any service. At the end, quote every input you sent to the Hub.

Paqari's interface hides the arguments of the tools it calls, which is why the prompt asks for them.

If the agent offers to publish your service, say no; a CREATED service runs as a service job. The Hub MCP also carries publish and delete tools, so if your assistant asks you to approve tool calls, approve only the job run and reads.

If every run call fails with 400 Input must be a JSON object, whatever the input, your client sent the job input as text rather than as a JSON object. Claude Code did this on 29 September 2026. Use Paqari, or run the job yourself with qhubctl run as in Step 4.

6Step 6: Chain it with a second service in a workflow (optional)

Your greedy returns 123, and Step 2 said the optimum is 135. A second service can say so on every run: a plan checker takes the district and a plan, and returns whether the plan is feasible, its objective, the optimum found by trying all 2^n plans, and the gap. A workflow chains the two, so one job runs the greedy and hands its plan to the checker.

Build the checker the way you built the greedy, in a folder next to it, with lighter hints this time:

qhubctl init --name t4-plan-checker --non-interactive
cd t4-plan-checker

from itertools import combinations
from typing import Dict, List

from pydantic import BaseModel

class InputData(BaseModel):
    """The district from Step 2 plus the plan to check."""

    net_value: List[float]
    overlap: Dict[str, float]
    exclusions: List[List[int]]
    chosen_sites: List[int]

class InputParams(BaseModel):
    pass

class CheckResult(BaseModel):
    feasible: bool
    objective: float
    optimum: float
    optimal_sites: List[int]
    gap: float

def _objective(sites, data: InputData) -> float:
    s = set(sites)
    penalty = sum(w for k, w in data.overlap.items() if {int(x) for x in k.split(",")} <= s)
    return sum(data.net_value[i] for i in s) - penalty

def _feasible(sites, data: InputData) -> bool:
    s = set(sites)
    return not any(a in s and b in s for a, b in data.exclusions)

def run(data: InputData, params: InputParams) -> CheckResult:
    """Check a plan and compare it with the best plan, found by trying all 2^n of them."""
    n = len(data.net_value)
    plans = [p for r in range(n + 1) for p in combinations(range(n), r) if _feasible(p, data)]
    best = max(plans, key=lambda p: _objective(p, data))
    objective, optimum = _objective(data.chosen_sites, data), _objective(best, data)
    return CheckResult(
        feasible=_feasible(data.chosen_sites, data),
        objective=objective,
        optimum=optimum,
        optimal_sites=list(best),
        gap=optimum - objective,
    )

{"net_value": [29, 17, 22, 0, 12, 37, 14, 16, 34, 12, 24, 20], "overlap": {"0,4": 23, "0,7": 9, "0,8": 9, "1,3": 23, "1,7": 6, "2,6": 10, "2,8": 23, "3,6": 21, "3,9": 20, "4,5": 22, "5,11": 14, "6,10": 17, "8,10": 14, "8,11": 12}, "exclusions": [[0, 3], [2, 7], [5, 9]], "chosen_sites": [0, 1, 5, 6, 7, 8]}

Run it locally, then deploy it:

uv run python -m src
qhubctl openapi
qhubctl get-context
qhubctl up

out/output.json shows feasible true, objective 123.0, optimum 135.0 and gap 12.0. As in Step 4, get-context must name your personal account before up.

A workflow calls services through a subscription, so both services need one. On each service's page, choose Publish Service, then Internal: the service stays off the Marketplace and becomes available to your own applications. Then create an Application and subscribe it to both services. Using a service walks through both, click by click. A free account allows three internal publications, and this step uses two.

Now build the workflow in the Hub's modeler, as the workflow introduction describes:

1. A start event. The workflow's input is one variable, district, holding the district.
2. A service task "Greedy plan" that calls t4-antenna-greedy through your subscription. Its input mapping: local variable name data, variable assignment value =district. Its output mapping: greedySites from =chosen_sites.
3. A service task "Check the plan" that calls t4-plan-checker.
4. An end event.

What do you think is happening here?

={net_value: district.net_value, overlap: district.overlap, exclusions: district.exclusions, chosen_sites: greedySites}

Deploy the workflow and run it. The Run form has no fields, because the workflow carries no API description, so choose Manual JSON input and paste the district under its variable name:

{"district": {"net_value": [29, 17, 22, 0, 12, 37, 14, 16, 34, 12, 24, 20], "overlap": {"0,4": 23, "0,7": 9, "0,8": 9, "1,3": 23, "1,7": 6, "2,6": 10, "2,8": 23, "3,6": 21, "3,9": 20, "4,5": 22, "5,11": 14, "6,10": 17, "8,10": 14, "8,11": 12}, "exclusions": [[0, 3], [2, 7], [5, 9]]}}

You should see both tasks succeed. Open the checker's execution under Service Executions: feasible true, objective 123, optimum 135, optimal_sites [0, 1, 2, 5, 10, 11] and gap 12. The run took 24 s on 29 September 2026. The workflow's own result stays empty unless its end event maps variables out; the air traffic tutorial builds a longer workflow that does.

The gap of 12 is the opening for the hand-off below: a better solver in the first task closes it, and the checker tells you on every run.

In a nutshell, building a service happens in three steps: init, serve and up, and qhubctl run allows you to test it. Users and agents can read your specifications and submit a suitable problem to your solver. Intelligent input and error handling speeds up any debugging process and guides users to the solution. Any other service can be built on the Kipu Quantum Hub similarly, either as an individual solver or as an orchestration of solvers in a workflow. Publishing a service makes it available to other users, their code and their agents.

Apply what you learned: swap the greedy solver for a quantum solver, or chain it into a workflow. The possibilities of your first quantum-centric application are vast. If you take one piece of advice from us, start from your recent work. Where could you apply this technology? Build it in a domain you already know. The next step is yours.

• Publish on the Marketplace, so other users can subscribe to your service.
• Use a service from an application, the way their code will call yours.

Documentation: Kipu Quantum Hub | Hub docs | Quickstart | CLI reference | MCP server | Access tokens | Workflows | Paqari