qpiai-quantum-agent-tools 0.1.0

Local MCP server exposing QpiAI Quantum SDK tools to agent harnesses

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

Install the package directly:

pip install qpiai-quantum-agent-tools

---

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.

OpenCode Configuration (opencode.jsonc)

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

Claude Desktop Configuration (claude_desktop_config.json)

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

Note: If the qpiai-quantum-mcp command is not on your system PATH, replace "qpiai-quantum-mcp" in the configurations above with the absolute path to the executable inside the Python environment where the package was installed (e.g., "C:/path/to/venv/Scripts/qpiai-quantum-mcp.exe" or "/path/to/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."