Skip to main content

MCP Quickstart

Get an AI agent calling QCOS in under 5 minutes.

Prerequisites​

  • QCOS API key — get one at portal.softquantus.com
  • Python 3.10+ with pip
  • Claude Desktop, or anthropic Python SDK

Option A — Claude Desktop​

1. Install the MCP server

pip install softquantus-mcp
# or: uvx softquantus-mcp  (no install)

2. Add to Claude Desktop config

claude_desktop_config.json
{
  "mcpServers": {
    "softquantus": {
      "command": "softquantus-mcp",
      "env": {
        "QCOS_API_KEY": "sk-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

3. Restart Claude Desktop and ask:

"List available quantum backends, pick the one with the best calibration score, and run a 2-qubit Bell state circuit on it with 1024 shots."

Claude will call qcos_list_backends, then qcos_submit_circuit, then qcos_get_job_result — and return the counts and DRR reliability score.

Option B — Python agent​

import anthropic
import os

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=2048,
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.softquantus.com/sse",
            "name": "softquantus",
            "authorization_token": os.environ["QCOS_API_KEY"],
        }
    ],
    messages=[
        {
            "role": "user",
            "content": """
                Run a VQE calculation for H2 molecule on the ibm-brisbane backend.
                Return the ground state energy estimate and the reliability score.
            """,
        }
    ],
    betas=["mcp-client-2025-04-04"],
)

print(response.content)

Option C — LangChain agent​

from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate
from langchain_anthropic import ChatAnthropic

async def main():
    async with MultiServerMCPClient(
        {
            "softquantus": {
                "url": "https://mcp.softquantus.com/sse",
                "transport": "sse",
                "headers": {"Authorization": f"Bearer {QCOS_API_KEY}"},
            }
        }
    ) as mcp_client:
        tools = mcp_client.get_tools()

        llm = ChatAnthropic(model="claude-sonnet-4-6")
        prompt = ChatPromptTemplate.from_messages([
            ("system", "You are a quantum computing assistant with access to QCOS, QuantumLock, and SynapseX tools."),
            ("human", "{input}"),
            ("placeholder", "{agent_scratchpad}"),
        ])

        agent = create_tool_calling_agent(llm, tools, prompt)
        executor = AgentExecutor(agent=agent, tools=tools)

        result = await executor.ainvoke({
            "input": "Run QAOA for a 4-node max-cut problem and return the solution."
        })
        print(result["output"])

What happens under the hood​

When the agent calls qcos_submit_circuit:

  1. MCP server validates the circuit (OpenQASM 3 or Qiskit serialized JSON)
  2. Calls POST /v2/jobs on the QCOS REST API
  3. Polls GET /v2/jobs/{id} until the job completes (or times out)
  4. Returns counts, DRR score, and backend metadata as structured JSON

The agent receives typed data it can reason about — not raw HTTP responses.

Next steps​