Skip to main content

SoftQCOS MCP

PyPI version Python 3.11+

A Model Context Protocol server that gives an AI agent typed tools over the QCOS REST API at https://api.softquantus.com. Each tool is one call to that API, made with the caller's own API key. The server has no privileges of its own and runs nothing the API does not serve.

The MCP server, the Python SDK (softqcos-sdk) and the CLI (softqcos) are released together and always carry the same version number. The table at the end of this page lists which tools each version added.

Install

pip install softqcos-mcp

Python 3.11 or newer. The package installs one command, softqcos-mcp, which starts the server. It installs softqcos-sdk as a dependency.

Run it

softqcos-mcp

The server speaks Streamable HTTP (stateless) and listens on http://127.0.0.1:8100/mcp, this machine only. Stop it with Ctrl-C. softqcos-mcp --help and softqcos-mcp --version print and exit without starting a server.

Check that it is up:

curl -s http://127.0.0.1:8100/health

It answers {"status":"ok","service":"softqcos-mcp"}.

For a client that starts its MCP servers itself, over stdin/stdout, run it as softqcos-mcp --transport stdio (see Claude Desktop below). Over stdio there is no header to carry a key, so the tools act for the key in QCOS_API_KEY.

Flag Environment variable Default Meaning
--transport http http (Streamable HTTP on /mcp) or stdio
--host SOFTQCOS_MCP_HOST 127.0.0.1 HTTP address to bind
--port SOFTQCOS_MCP_PORT 8100 HTTP port to bind
QCOS_API_KEY none your key; over stdio every tool uses it
QCOS_API_URL https://api.softquantus.com the QCOS API the tools call
QCOS_LOG_LEVEL info server log level
QCOS_ENV development production requires a bearer token on /mcp, see below
QCOS_MCP_BEARER_TOKEN none the token /mcp demands when QCOS_ENV=production

A flag wins over its environment variable. Binding anything other than loopback (--host 0.0.0.0) exposes /mcp to the network; read "Running it for others" first.

Your API key

Create an API key at https://platform.softquantus.com/#apikeys. The MCP client sends it on every request in the x-api-key header (x-qcos-api-key is accepted too). The server forwards it to the API for that call and keeps nothing.

Identity comes from the key alone. x-tenant-id, x-project-id and x-user-id headers are ignored: anyone could write any value in them.

Connect a client

Claude Code:

claude mcp add --transport http softqcos http://127.0.0.1:8100/mcp --header "x-api-key: $QCOS_API_KEY"

Cursor (.cursor/mcp.json) and other clients that take a URL and headers:

{
  "mcpServers": {
    "softqcos": {
      "url": "http://127.0.0.1:8100/mcp",
      "headers": { "x-api-key": "<your key>" }
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "softqcos": {
      "type": "http",
      "url": "http://127.0.0.1:8100/mcp",
      "headers": { "x-api-key": "${input:qcos-api-key}" }
    }
  },
  "inputs": [
    { "id": "qcos-api-key", "type": "promptString", "description": "QCOS API key", "password": true }
  ]
}

Claude Desktop (claude_desktop_config.json) starts the server itself, over stdio:

{
  "mcpServers": {
    "softqcos": {
      "command": "softqcos-mcp",
      "args": ["--transport", "stdio"],
      "env": { "QCOS_API_KEY": "<your key>" }
    }
  }
}

If Claude Desktop cannot find softqcos-mcp, put the full path that which softqcos-mcp prints in command.

From Python, with the mcp package this server already depends on:

import asyncio
import os

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client


async def main() -> None:
    headers = {"x-api-key": os.environ["QCOS_API_KEY"]}
    async with streamablehttp_client("http://127.0.0.1:8100/mcp", headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = (await session.list_tools()).tools
            print(len(tools), "tools")
            result = await session.call_tool("qcos_get_v1_runtime_capabilities", {})
            print(result.structuredContent)


asyncio.run(main())

What each tool needs

Every tool belongs to one class, and the class decides what the caller must present. A tool refused for a missing requirement returns an error result that names the reason; it never runs halfway.

Class What it does Caller key Entitlement
public catalogues, backend lists, estimates, health not needed not needed
tenant reads, cancels and releases your own jobs, evidence, sessions required not needed
compute uses QCOS compute without naming a device required required
device sends work to a named backend (backend_id) required required, for that backend

Public examples: qcos_get_v1_runtime_capabilities, qcos_get_v1_backends, qcos_post_v1_estimate, qcos_qec_codes_catalog. Tenant examples: qcos_get_v1_jobs, qcos_get_v1_jobs_job_id_result, qcos_get_v1_runtime_jobs_job_id_execution_evidence. Device example: qcos_post_v1_jobs.

Tenant tools stay available when an entitlement has run out, so a job can always be read and cancelled.

"Not needed" is this server's own check: it forwards a public call without asking for a key. The API can still ask for one, and api.softquantus.com does for most public tools (qcos_get_v1_runtime_capabilities needs a key with qcos:read), so send your key on every call. A public call that arrives without x-api-key goes out under the server process's own QCOS_API_KEY when one is set, and with no key otherwise.

Compute and device tools check the entitlement with the QCOS server's own gate, which ships with the QCOS server and not with this package. A server started from pip install softqcos-mcp cannot load it, so it refuses those tools with entitlement_gate_unavailable instead of running them unchecked. Public and tenant tools work. To run a circuit from your own machine today, use the SDK or the CLI, which call the API directly and are checked there.

Running it for others

QCOS_ENV=production makes /mcp demand Authorization: Bearer <QCOS_MCP_BEARER_TOKEN> on every request, and the server refuses to start without that token. The bearer token says which gateway is calling; it is shared by every caller and identifies no customer, so each request still needs the customer's own x-api-key. /health is always open.

Do not set QCOS_API_KEY on a server other people call: their public calls without a key of their own would run under it.

Put the server behind TLS before it leaves the machine. API keys travel in a header, and plain HTTP shows them to anyone on the path.

What each version added

Generated from the code at release time, so it cannot drift from what this version runs. Tool names as a client sees them.

Package version on this source tree: 3.10.0. softqcos-sdk, softqcos and softqcos-mcp always carry the same number, so the row a name sits in is the first version of THIS package that has it. A version is listed once it is tagged; it reaches PyPI when that release is published, and pip index versions softqcos-mcp shows which versions PyPI has.

Version Added
3.10.0 qcos_science_algorithm, qcos_science_algorithms, qcos_science_capabilities, qcos_science_eigensolve, qcos_science_evolve, qcos_science_optimize, qcos_science_plan, qcos_science_resource_estimate, qcos_science_simulate_quantum_system, qcos_science_validate
3.9.0 qcos_delete_v1_hal_jobs_job_id, qcos_get_v1_hal_backends, qcos_get_v1_hal_backends_name, qcos_get_v1_hal_jobs_job_id, qcos_get_v1_hal_jobs_job_id_result, qcos_post_v1_hal_jobs, qcos_quantus_analyze_problem, qcos_quantus_build_problem, qcos_quantus_compile_problem, qcos_quantus_execute, qcos_quantus_execution_store, qcos_quantus_explain_coefficient, qcos_quantus_explain_execution, qcos_quantus_get_advantage, qcos_quantus_get_evidence, qcos_quantus_get_execution, qcos_quantus_get_lifecycle, qcos_quantus_list_backends, qcos_quantus_normalize_data, qcos_quantus_routing_rules, qcos_quantus_seal_execution, qcos_quantus_suitability, qcos_quantus_validate_problem, qcos_research_apps_get, qcos_research_apps_list, qcos_research_apps_molecular_vqe_run, qcos_research_apps_plan
3.8.3 qcos_get_v1_runtime_evidence, qcos_get_v1_runtime_evidence_list, qcos_get_v1_runtime_evidence_trust, qcos_post_v1_runtime_evidence_verify
3.8.2 qcos_post_v1_runtime_dynamics_analyze, qcos_post_v1_runtime_state_analyze
<=3.8.0 86 tools, all present in 3.8.0, the first version of the shared numbering

License

Copyright © 2024-2026 SoftQuantus innovative OÜ. All Rights Reserved.

QCOS™ is a trademark of SoftQuantus innovative OÜ. Registry Code: 17048927 | Tallinn, Estonia

Metadata

Release files for softqcos-mcp 3.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for softqcos-mcp 3.10.0
File Size Uploaded Provenance Actions
softqcos_mcp-3.10.0.tar.gz 108.7 kB With provenance Details for softqcos_mcp-3.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for softqcos-mcp 3.10.0
File Interpreter ABI Platform Actions
softqcos_mcp-3.10.0-py3-none-any.whl Python 3 none any Details for softqcos_mcp-3.10.0-py3-none-any.whl

Total release size: 204.6 kB

Release files / softqcos_mcp-3.10.0.tar.gz

Download URL softqcos_mcp-3.10.0.tar.gz
Size 108.7 kB
Tags Source
SHA-256 checksum
How to use checksums
f6a5d6432809b0541a381e22215dbe87e7d342d0ca1d500f550f7fb64dbe9b79
BLAKE2b-256 checksum
How to use checksums
83d28d3fb20f15f751217b25463b610e2a18acbf5c8e3adc16ac4ef958db01e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.

Transparency log

Release files / softqcos_mcp-3.10.0-py3-none-any.whl

Download URL softqcos_mcp-3.10.0-py3-none-any.whl
Size 95.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3f3bf58cbe6857dd3a4bce8d329b0e3e131495b6d07f4b0f9f0d658562462f1e
BLAKE2b-256 checksum
How to use checksums
19daadcb911617f556c04fe4b6bd6b14ef14fa5d1f5d10167accba7033de52cf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.

Transparency log

Security for softqcos-mcp 3.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for softqcos_mcp-3.10.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page