QpiAI Quantum Agent Tools

An MCP (Model Context Protocol) server that exposes the QpiAI Quantum SDK as tools for AI agent interfaces (such as OpenCode, Claude Desktop, and Cursor).

Installation

You can install the package either globally (so the command is available anywhere) or inside a local virtual environment.

1. Global Installation (Recommended)

This registers the qpiai-quantum-mcp command globally on your system so you don't need to specify absolute virtual environment paths in your config.

• Using standard pip:

  pip install qpiai-quantum-agent-tools
  

• Using uv:

  uv tool install qpiai-quantum-agent-tools
  

2. Local Virtual Environment Installation

If you prefer installing it inside an isolated project virtual environment:

• Using standard pip:

  pip install qpiai-quantum-agent-tools
  

• Using uv (add the --compile-bytecode flag to compile files during installation and prevent first-run startup delay):

  uv pip install qpiai-quantum-agent-tools --compile-bytecode
  

Configuration & Usage

Authentication requires a QpiAI API key. You can run the MCP server in one of two modes:

1. stdio Mode

The server runs directly as a subprocess managed by your AI agent interface. Configure it by adding the server definition under the environment settings in the client's configuration file.

Finding Your Config File

• OpenCode (opencode.jsonc):
  • Windows: C:\Users\<username>\.config\opencode\opencode.jsonc
  • Linux/macOS: ~/.config/opencode/opencode.jsonc
• Claude Desktop (claude_desktop_config.json):
  • Windows: C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Other applications (e.g., Cursor, Cline, Roo Code):
  • Please search online or consult the application's documentation to find the location of its MCP configuration file.

Configuration for Global Installation

If you installed the package globally, use the command name "qpiai-quantum-mcp" directly:

OpenCode (opencode.jsonc)

{
  "mcp": {
    "qpiai-quantum": {
      "type": "local",
      "command": ["qpiai-quantum-mcp"],
      "env": {
        "API_KEY": "your_qpiai_api_key_here"
      },
      "enabled": true
    }
  }
}

Claude Desktop / Cursor

{
  "mcpServers": {
    "qpiai-quantum": {
      "command": "qpiai-quantum-mcp",
      "env": {
        "API_KEY": "your_qpiai_api_key_here"
      }
    }
  }
}

Configuration for Local Virtual Environment

If you installed the package inside a local project virtual environment, specify the absolute path to the executable inside that environment:

OpenCode (opencode.jsonc)

{
  "mcp": {
    "qpiai-quantum": {
      "type": "local",
      "command": [
        "C:/path/to/your/venv/Scripts/qpiai-quantum-mcp.exe"
      ],
      "env": {
        "API_KEY": "your_qpiai_api_key_here"
      },
      "enabled": true
    }
  }
}

(On Linux/macOS, use the path "/path/to/your/venv/bin/qpiai-quantum-mcp")

Claude Desktop / Cursor

{
  "mcpServers": {
    "qpiai-quantum": {
      "command": "C:/path/to/your/venv/Scripts/qpiai-quantum-mcp.exe",
      "env": {
        "API_KEY": "your_qpiai_api_key_here"
      }
    }
  }
}

(On Linux/macOS, use the path "/path/to/your/venv/bin/qpiai-quantum-mcp")

2. HTTP Mode

For lower latency across multiple agent sessions, you can run the server as a persistent HTTP local server.

1. Set the API Key in the terminal where you will start the server:

   • PowerShell: $env:API_KEY="your_qpiai_api_key_here"
   • Command Prompt: set API_KEY=your_qpiai_api_key_here
   • Linux/macOS: export API_KEY="your_qpiai_api_key_here"
   • Alternative: Create a .env file containing API_KEY=your_qpiai_api_key_here in the directory where you run the server.

2. Start the HTTP Server: Run the following command in the terminal where the package was installed:

   qpiai-quantum-mcp --http
   

   By default, the server starts on http://127.0.0.1:8080/mcp.

   If the command is not recognized or not on your system PATH, you can run it via its absolute path or using Python:

   python -m qpiai_quantum_agent_tools.server --http
   

   Options:

   • --port PORT — Custom port (default: 8080)
   • --host HOST — Custom bind host (default: 127.0.0.1)

3. Configure your client to connect to the URL:

   • OpenCode (opencode.jsonc):

     {
       "mcp": {
         "qpiai-quantum": {
           "type": "remote",
           "url": "http://127.0.0.1:8080/mcp",
           "enabled": true
         }
       }
     }
     

   • Claude Desktop / Cursor:

     {
       "mcpServers": {
         "qpiai-quantum": {
           "url": "http://127.0.0.1:8080/mcp"
         }
       }
     }
     

Tools

• qpiai_health_check: Reports SDK import status, active transport (stdio/http), and whether an API key is configured.
• qpiai_verify_api_key: Validates the configured key against QpiAI.
• qpiai_get_user_details: Retrieves the name and email of the authenticated user.
• qpiai_list_compute_resources: Lists available compute resources for the configured key.
• qpiai_validate_qasm: Performs basic OpenQASM sanity checks.
• qpiai_submit_qasm_job: Dry-runs by default; submits only when run=true.
• qpiai_get_job_status: Fetches job status by ID.
• qpiai_get_job_result: Fetches parsed job result data by ID.
• qpiai_get_job_history: Retrieves recent job submission history with optional status and period filtering.
• qpiai_simulate_local: Runs a local statevector simulator on custom circuit JSON.

Example Prompts

• "Check whether QpiAI Quantum is configured."
• "List my available QpiAI compute resources."
• "Validate this Bell-state OpenQASM without submitting it."
• "Dry-run a submission of this QASM to QpiAI-QSV-Simulator with 1024 shots."
• "Submit this QASM with run=true after confirming the simulator and shot count."