Configuration Guide

The QCOS MCP server can be configured for local desktop use (Stdio mode) or hosted web/container environments (Streamable HTTP mode).

1. Local Desktop Config (Claude Desktop)

To enable QCOS tools in Claude Desktop, add the server declaration to your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Stdio JSON Configuration

Open the configuration file and merge the mcpServers block:

{
  "mcpServers": {
    "softqcos-mcp": {
      "command": "softqcos-mcp",
      "env": {
        "QCOS_API_URL": "https://api.softquantus.com",
        "QCOS_API_KEY": "sq-live-your-key",
        "QUANTUMLOCK_LICENSE_PATH": "/Users/yourusername/.softqcos/license.qlicense"
      }
    }
  }
}

Note: Make sure softqcos-mcp is installed in your system PATH, or provide the absolute path to the executable (e.g. /usr/local/bin/softqcos-mcp).

2. Environment Variables Registry

The MCP server checks the following variables at startup:

Variable	Default Value	Description
`QCOS_API_KEY`	`""`	Your SoftQuantus API Key. Required to authorize requests.
`QCOS_API_URL`	`https://api.softquantus.com`	Target gateway url. Set to `http://localhost:8000` to target your local simulator daemon.

3. Hosted Streamable HTTP Deployment

For hosted deployments where multiple AI agents or web backends connect over the network, run the ASGI app in Streamable HTTP mode:

uvicorn softqcos_mcp.http_server:app --host 0.0.0.0 --port 8199

Inbound calls carry two identities: Authorization: Bearer <service token> (the calling service) and X-API-Key: sq-live-... (the customer whose quota and data the tools act on). The hosted production endpoint is https://mcp.softquantus.com/mcp.

Docker Container Run

Deploy the official compiled MCP container:

docker run -d \
  --name qcos-mcp-server \
  -e QCOS_API_URL="https://api.softquantus.com" \
  -e QCOS_API_KEY="sq-live-your-key" \
  -p 8199:8199 \
  sqtprodacr.azurecr.io/sqt/softqcos-mcp:latest

Docker Compose Configuration

To deploy as part of a local microservices stack, define the service in your docker-compose.yml:

version: '3.8'
services:
  qcos-mcp:
    image: sqtprodacr.azurecr.io/sqt/softqcos-mcp:latest
    container_name: qcos-mcp-server
    ports:
      - "8199:8199"
    environment:
      - QCOS_API_URL=https://api.softquantus.com
      - QCOS_API_KEY=${QCOS_API_KEY}
    restart: always

4. Verification & Debugging

If tools are not loading in your AI interface, check the logs or run the command manually to verify that the server boots:

1. Manual Stdio Test

Run the command in your terminal. It should sit waiting for JSON-RPC input. If it exits immediately with an error, look at the output:

softqcos-mcp

2. Check Claude Desktop Logs

If Claude fails to connect to the server, review the logs to check for pathing or env var errors:

tail -n 50 ~/Library/Logs/Claude/mcp.log

3. HTTP Health Probe

For hosted deployments, hit the unauthenticated health route to confirm connectivity:

curl -f http://localhost:8199/health

LLM Tools

MCP Configuration

Configuration Guide

1. Local Desktop Config (Claude Desktop)

Stdio JSON Configuration

2. Environment Variables Registry

3. Hosted Streamable HTTP Deployment

Docker Container Run

Docker Compose Configuration

4. Verification & Debugging

1. Manual Stdio Test

2. Check Claude Desktop Logs

3. HTTP Health Probe

​Configuration Guide

​1. Local Desktop Config (Claude Desktop)

​Stdio JSON Configuration

​2. Environment Variables Registry

​3. Hosted Streamable HTTP Deployment

​Docker Container Run

​Docker Compose Configuration

​4. Verification & Debugging

​1. Manual Stdio Test

​2. Check Claude Desktop Logs

​3. HTTP Health Probe

Configuration Guide

1. Local Desktop Config (Claude Desktop)

Stdio JSON Configuration

2. Environment Variables Registry

3. Hosted Streamable HTTP Deployment

Docker Container Run

Docker Compose Configuration

4. Verification & Debugging

1. Manual Stdio Test

2. Check Claude Desktop Logs

3. HTTP Health Probe