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