---
url: /agentic/usecase-to-service-agentic.md
description: >-
  Build, test, and deploy a quantum service end-to-end using qhubctl and the
  Kipu Quantum Hub MCP server with an AI coding assistant.
---

# Tutorial: Quantum Application Development with Kipu Quantum Hub MCP Server

In this tutorial, you will learn how to develop quantum services using the Kipu Quantum Hub MCP server.
You will learn how to use the MCP server to:

1. Find suitable use cases that match your business domain and objectives
2. Discover relevant quantum services on the Kipu Quantum Hub
3. Implement quantum applications using the identified services and use cases
4. Test your implementation locally
5. Deploy your service to Kipu Quantum Hub

In this tutorial, we use the **airline industry** as an example business domain.

## Prerequisites

* **qhubctl** installed (see [CLI installation guide](../cli-reference))
* **Access to Kipu Quantum Hub** (sign up at <https://hub.kipu-quantum.com>)
* **Personal Access Token** for Kipu Quantum Hub
* **AI coding assistant** that supports MCP servers (e.g., Claude Code, GitHub Copilot, etc.). We will use Claude Code in this tutorial, but feel free to use any AI coding assistant that supports MCP servers

## 1. Setup

We will use our CLI `qhubctl` to set up a new `Python Starter` project for the Kipu Quantum Hub.

### Create a New Project

Create a new project using the following command:

```bash
qhubctl init
```

You will be prompted to provide some information about your project. For this tutorial, select:

* **Service name**: Choose a meaningful name (e.g., `airline-optimization-service`)
* **Starter template**: `Python Starter`
* **vCPU configuration**: `1 vCPU`
* **Memory configuration**: `1GB`

This will create a new directory containing all required files to run your quantum code on Kipu Quantum Hub.

### Configure the MCP Server

Once the project is created, add the Kipu Quantum Hub MCP server to your AI coding assistant.

**For Claude Code users:**
The project is already set up with a `.mcp.json` file in your project directory. Update the file with your personal access token:

```json
{
  "mcpServers": {
    "qhub-mcp": {
      "command": "uvx",
      "args": ["qhub-mcp@latest"],
      "env": {
        "KQH_PERSONAL_ACCESS_TOKEN": "${KQH_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}
```

**For other AI coding assistants:**
Please refer to the documentation of your AI coding assistant on how to add MCP servers. See the [MCP Server documentation](mcp-server.md) for more details.

## 2. Identifying Relevant Use Cases

Once everything is set up, you can start by asking your AI coding assistant to help you identify relevant use cases for quantum computing.

The MCP server provides access to the Kipu Quantum Hub's use case repository, which contains industry-specific quantum computing applications.

### Example Prompt

Ask your AI coding assistant:

> What are some relevant use cases for quantum computing in the airline industry? Please provide a list of use cases along with a brief description of each.

Your AI assistant will query the Kipu Quantum Hub MCP server and return relevant use cases. For example:

> Based on my search of the Kipu Quantum Hub platform, here are relevant quantum computing use cases for the airline industry:
>
> 1. Multi-Aircraft Routing
>    Finding collision-free routes for multiple aircraft with defined start and destination locations. Aircraft move through a predefined grid structure to avoid conflicts.
>    Application: Air traffic management, flight path optimization
>    Method: Quantum annealing approaches
>
> 2. Single Vehicle Routing
>    Pathfinding along grid points from start to destination using quantum annealing algorithms.
>    Application: Individual flight route optimization, ground vehicle routing at airports
>    Method: Quantum annealing

Review the use cases and select the one that best aligns with your business objectives.
For this tutorial, we'll focus on the **Multi-Aircraft Routing** use case.

## 3. Discovering Quantum Services

Now that we've selected the \*\*Multi-Aircraft Routing
\*\* use case, we need to find quantum services on the Kipu Quantum Hub that can solve this type of problem.

The MCP server enables your AI assistant to search through available services and understand their capabilities.

### Example Prompt

Ask your AI coding assistant with a use case-specific prompt:

> For the Multi-Aircraft Routing use case, find quantum services offered by Kipu Quantum on the Kipu Quantum Hub that are suitable for solving this routing optimization problem. Please provide a list of services along with their descriptions and capabilities.

Your AI assistant will search the Kipu Quantum Hub marketplace and return relevant services that can handle routing optimization problems. Here are some example services it might find:

> **Based on the Multi-Aircraft Routing use case, here are some relevant quantum services available on the Kipu Quantum Hub:**
>
> 1. Illay Base Quantum Optimizer *(FREE)*:\
>    Free quantum optimizer using **DCQO** (Digitized Counterdiabatic Quantum Optimization) on IBM Aer simulator.
>
> 2. Miray Advanced Quantum Optimizer *(PREMIUM)*:\
>    Cutting-edge bias field quantum optimization running on actual IBM quantum hardware. Uses the **bf-DCQO** (bias-field Digitized Counterdiabatic Quantum Optimization) algorithm for production-scale problems.
>
> *All services accept **QUBO/Ising** problem formulations, which is the standard format for encoding the Multi-Aircraft Routing constraints (collision avoidance, time-based routing, path optimization) as described in the use case documentation.*

The AI assistant can also provide details about:

* Service input/output formats
* Supported quantum backends and hardware
* Pricing information
* Documentation and code examples
* How the service maps to the Multi-Aircraft Routing problem

## 4. Implementing Quantum Applications

Now that you have identified a use case and discovered relevant services, it's time to implement your quantum application.

Your AI coding assistant can help you write the code that integrates with the selected quantum service.

### Example Prompt

For the Air Traffic Management use case, you might prompt:

> Help me implement a managed service for the Kipu Quantum Hub that uses the Illay Base Quantum Optimizer to solve an air traffic management problem.
> Implement a small example 5 flight routes with some intersections. Ensure that it is feasible to be solved with the Iskay Base Quantum Optimizer.
> The following constraints must be considered:
>
> * Minimize the number of vertical corridors used
> * Intersecting routes cannot share the same corridor.
> * Minimize total distance, fuel consumption, or time based on corridor assignments
>   Please use the service we found earlier and implement the encoding, execution, and decoding steps. For implementation use the project we are currently in.

### What Your AI Assistant Will Do

Your AI assistant will:

1. **Analyze the service API**: Understand the input/output format required by the service
2. **Write the encoding logic**: Convert your problem (flight routes, intersections) into a format the quantum service accepts
3. **Implement service execution**: Use the qhub-service library to execute a service
4. **Write the decoding logic**: Convert the quantum solution back into flight corridor assignments
5. **Add error handling**: Ensure robust execution with proper exception handling

### Working Collaboratively with Your AI Assistant

As you implement your application:

* Ask the AI assistant to explain the quantum service's input format
* Request help with data transformations
* Ask for code improvements and optimizations
* Get assistance with debugging and error handling

The AI assistant has access to the service documentation through the MCP server, so it can provide accurate, up-to-date implementation guidance.

## 5. Testing Locally

Before deploying your service to Kipu Quantum Hub, test it locally to ensure it works correctly.

### Install Dependencies

First, navigate to your project directory and install the required dependencies:

```bash
cd airline-optimization-service
```

Create a virtual environment and install dependencies:

```bash
# Using uv (recommended)
uv venv
uv sync
source .venv/bin/activate

# Or using pip
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### Test Using Python Directly

Run your service directly with Python:

```bash
python -m src
```

This will execute your service with the default input data defined in `input/data.json` and `input/params.json`.

### Test Using the CLI

For a more realistic test that simulates the platform environment, use `qhubctl`:

```bash
qhubctl serve
```

This starts a local server on `http://localhost:8081`.
Once the server is operational, you can access <http://localhost:8081/docs>.
This interface provides you the ability to run your current code and see the results.
Further information can be found in the [CLI reference](../cli-reference#qhubctl-serve).

### Get Help from Your AI Assistant

If you encounter errors during testing, ask your AI assistant for help:

> I'm getting an error when testing my service locally: \[paste error message]. Can you help me debug this?

Your AI assistant can analyze the error, check service documentation via the MCP server, and suggest fixes.

## 6. Deploying to Kipu Quantum Hub

Once you have tested your service locally and verified it works correctly, deploy it to Kipu Quantum Hub.

### Deploy Using the CLI

From your project directory, run:

```bash
qhubctl up
```

This command will:

1. Package your project (respecting `.dockerignore` exclusions)
2. Upload it to Kipu Quantum Hub
3. Trigger the containerization process
4. Create a managed service

After successful deployment, you will see a message with the service URL.

### Verify Your Deployment

1. Navigate to the [Services page](https://dashboard.hub.kipu-quantum.com/services) on Kipu Quantum Hub
2. Find your newly created service in the list
3. Click on it to view the service details
4. Wait for the containerization to complete (status will change to "RUNNING")

### Execute Your Deployed Service

Execute your service using the CLI:

```bash
qhubctl run
```

This will:

* Use the input data from `input/data.json` and `input/params.json`
* Execute the service on Kipu Quantum Hub
* Display the execution status and result

## Next Steps

Congratulations! You have successfully:

* Identified quantum computing use cases for your domain using the MCP server
* Discovered relevant quantum services on Kipu Quantum Hub
* Implemented a quantum application with AI assistance
* Tested your implementation locally
* Deployed your service to Kipu Quantum Hub

## Additional Resources

* [qhubctl CLI Reference](../cli-reference.md)
* [MCP Server Documentation](mcp-server.md)
* [Managed Services Documentation](../services/managed/introduction.md)
* [Quickstart Guide](../quickstart.md)
* [Service SDK Reference](../sdk-service.md)