> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# QWED MCP: verification for Model Context Protocol

> QWED-MCP is a Model Context Protocol server that runs assistant-written Python scripts using QWED SDK verification libraries with the server's privileges.

**Model Context Protocol (MCP) Server for QWED Verification**

![PyPI version](https://img.shields.io/pypi/v/qwed-mcp)
![Tests](https://github.com/QWED-AI/qwed-mcp/actions/workflows/publish.yml/badge.svg)
![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)

QWED-MCP brings deterministic verification to Claude Desktop, VS Code, and any MCP-compatible AI assistant. Instead of trusting LLMs to compute correctly, QWED-MCP runs Python scripts written by the assistant, with access to the QWED SDK verification libraries. All verification runs locally.

Use QWED-MCP when you want an MCP-compatible assistant to run deterministic checks (math, logic, SQL, code) instead of computing answers itself.

<Warning>
  `execute_python_code` runs code in a subprocess **with the server's privileges**. It is not a sandbox. The subprocess gets a restricted set of environment variables, and calls pass through the `RiskBasedExecutionGateway`, but only enable code execution where you trust the inputs.
</Warning>

***

## Why QWED-MCP?

### The problem

LLMs are unreliable for:

* **Mathematical calculations** - They approximate, don't compute
* **Logical reasoning** - They guess patterns, don't prove
* **Code security** - They miss edge cases, don't analyze
* **SQL queries** - They don't validate, just generate

### The solution

QWED-MCP exposes **deterministic verification** to AI assistants through a single `execute_python_code` tool. The LLM writes a Python script that imports the appropriate QWED SDK, and the MCP server runs it in a subprocess with restricted environment variables and the server's privileges.

| Without QWED-MCP | With QWED-MCP |
| - | - |
| LLM-only math → approximated by the model | Script calls the QWED math engine → result computed by SymPy |
| LLM-only SQL → unchecked for injection | Script calls the QWED SQL analyzer → known injection patterns flagged |
| LLM-only reasoning → unchecked | Script calls Z3 via the SDK → the formal statement is checked; the result can also be inconclusive |
| LLM-only code → unchecked | Script runs an AST check → dangerous patterns flagged |

What a run checks depends entirely on which QWED SDK calls the script makes: executing a script is not itself verification. The formal statement is only as good as the script the assistant wrote, so review it. See [qwedai.tech/limits](https://qwedai.tech/limits).

***

## How it works

```text theme={null}
┌─────────────────────────────────────────────────────────────┐
│                    Your AI Application                       │
│  ┌─────────────────┐        ┌─────────────────────────────┐ │
│  │  Claude Desktop │        │        VS Code + Copilot    │ │
│  │  or any MCP     │        │        or any MCP Client    │ │
│  │  compatible     │        │                             │ │
│  └────────┬────────┘        └──────────────┬──────────────┘ │
└───────────┼─────────────────────────────────┼───────────────┘
            │                                 │
            │         MCP Protocol            │
            │       (JSON-RPC over stdio)     │
            ▼                                 ▼
┌──────────────────────────────────────────────────────────────┐
│                     QWED-MCP Server (v0.2.0)                 │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │          RiskBasedExecutionGateway                     │  │
│  │  └─► Policy lookup → Argument validation →            │  │
│  │      Code safety (AST) → Admin policy enforcement     │  │
│  ├────────────────────────────────────────────────────────┤  │
│  │              execute_python_code                       │  │
│  │  ├─► Synchronous Execution (30s timeout)               │  │
│  │  └─► Background Execution (background=true)            │  │
│  │       └─► Async Job Queue (up to 5 concurrent)         │  │
│  │           └─► Native QWED library execution            │  │
│  │               ├── qwed_new (math, logic, code, SQL)    │  │
│  │               ├── qwed_legal (deadlines, citations,..) │  │
│  │               ├── qwed_finance (banking, ISO 20022)    │  │
│  │               └── qwed_ucp (commerce verification)     │  │
│  ├────────────────────────────────────────────────────────┤  │
│  │              verification_status                       │  │
│  │  └─► Poll background job results by job_id             │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
└──────────────────────────────────────────────────────────────┘
```

***

## Available tools

| Tool | Description | Use case |
| - | - | - |
| [`execute_python_code`](/mcp/tools#execute_python_code) | Subprocess execution | The primary entry point for all QWED capabilities. Executes dynamically generated Python code with access to all QWED SDK libraries. Supports optional `background=true` for async execution. |
| [`verification_status`](/mcp/tools#verification_status) | Job status polling | Check the status and results of background verification jobs dispatched via `execute_python_code` with `background=true`. |

All tool calls pass through the [`RiskBasedExecutionGateway`](/mcp/tools#riskbasedexecutiongateway-governance) before dispatch. The gateway validates arguments, runs code safety analysis, and enforces admin policy. The gateway blocks unknown tools by default.

<Info>
  In v0.1.x, QWED-MCP exposed individual tools like `verify_math`, `verify_logic`, `verify_code`, and `verify_sql`. These were consolidated into `execute_python_code` in v0.2.0 to solve context bloat (RFC-9728 compatibility). See [migration guide](/mcp/tools#migrating-from-v0-1-x).
</Info>

***

## Installation

### From PyPI (recommended)

```bash theme={null}
pip install qwed-mcp
```

### From source

```bash theme={null}
git clone https://github.com/QWED-AI/qwed-mcp.git
cd qwed-mcp
pip install -e .
```

### Verify installation

```bash theme={null}
qwed-mcp --version
# qwed-mcp 0.2.0
```

***

## Quick start

### Claude Desktop setup

1. **Find your config file:**
   * **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
   * **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   * **Linux:** `~/.config/Claude/claude_desktop_config.json`
2. **Add QWED-MCP server:**

```json theme={null}
{
  "mcpServers": {
    "qwed-verification": {
      "command": "qwed-mcp",
      "env": {
        "QWED_MCP_TRUSTED_CODE_EXECUTION": "true"
      }
    }
  }
}
```

3. **Restart Claude Desktop**
4. **Test it!** Ask Claude:
   > "Write a Python script that verifies a \$10,000 investment at 7.5% for 5 years using the compound interest formula, and run it using execute\_python\_code."

### VS Code setup

1. **Install MCP extension** (if not already)
2. **Add to settings.json:**

```json theme={null}
{
  "mcp.servers": {
    "qwed-verification": {
      "command": "qwed-mcp",
      "env": {
        "QWED_MCP_TRUSTED_CODE_EXECUTION": "true"
      }
    }
  }
}
```

3. **Restart VS Code**

### Python client

You can also use QWED-MCP programmatically:

```python theme={null}
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="qwed-mcp",
        env={"QWED_MCP_TRUSTED_CODE_EXECUTION": "true"}
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[t.name for t in tools.tools]}")
            # Output: Available tools: ['execute_python_code', 'verification_status']
            
            # Run a verification script
            result = await session.call_tool(
                "execute_python_code",
                arguments={
                    "code": (
                        "from sympy import symbols, diff\n"
                        "x = symbols('x')\n"
                        "print(f'd/dx(x^3) = {diff(x**3, x)}')"
                    )
                }
            )
            print(result)

asyncio.run(main())
```

***

## Configuration

### Environment variables

| Variable | Description | Default |
| - | - | - |
| `QWED_MCP_TRUSTED_CODE_EXECUTION` | Enable `execute_python_code` tool (`true`/`false`) | `false` |
| `QWED_LOG_LEVEL` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |
| `QWED_TIMEOUT` | Synchronous tool execution timeout in seconds | `30` |
| `QWED_MCP_BACKGROUND_TIMEOUT` | Background worker timeout in seconds for jobs dispatched with `background=true`. Clamped to a hard ceiling of `600`. Non-numeric or non-positive values fall back to the default | `120` |
| `QWED_SKILL_MANIFEST` | Path to a skill manifest JSON file. When set, the server validates the manifest at startup using [`SkillProvenanceGuard`](/mcp/tools#skillprovenanceguard-security) and refuses to start if verification fails | Not set |

<Warning>
  Set `QWED_MCP_TRUSTED_CODE_EXECUTION` to `true` to enable code execution. The executed code runs with server privileges — ensure inputs are from trusted sources.
</Warning>

### Example with environment variables

**Windows (PowerShell):**

```powershell theme={null}
$env:QWED_MCP_TRUSTED_CODE_EXECUTION = "true"
$env:QWED_LOG_LEVEL = "DEBUG"
qwed-mcp
```

**macOS/Linux:**

```bash theme={null}
QWED_MCP_TRUSTED_CODE_EXECUTION=true QWED_LOG_LEVEL=DEBUG qwed-mcp
```

***

## Use cases

### 1. Financial calculations

Verify that AI-generated financial calculations are correct:

```text theme={null}
User: Calculate compound interest for $10,000 at 5% for 3 years

Claude: Let me verify this calculation.
        [Calls execute_python_code with a script using Decimal math]
        
        STDOUT: Future value = $11576.25
        ✅ Verified using deterministic decimal arithmetic.
```

### 2. Research validation

Ensure scientific claims are logically valid:

```text theme={null}
User: If all mammals are warm-blooded, and dolphins are mammals,
      are dolphins warm-blooded?

Claude: [Calls execute_python_code with a Z3 solver script]
        
        STDOUT: The conclusion logically follows from the premises.
        ✅ Verified via Z3 SMT solver.
```

### 3. Secure coding

Check AI-generated code for security issues:

```text theme={null}
User: Write a function to execute user commands

Claude: def run_command(cmd):
            os.system(cmd)
        
        [Calls execute_python_code with a CodeGuard script]
        
        STDOUT: Verified: False
          - Dangerous pattern: os.system
        
        ⚠️ Security issue detected. Here's a safer alternative...
```

### 4. SQL security

Check generated queries for SQL injection patterns:

```text theme={null}
User: Generate a query to find user "admin' OR '1'='1"

Claude: [Calls execute_python_code with a SQLGuard script]
        
        STDOUT: Verified: False
          - SQL injection pattern detected
        
        ❌ Injection detected. Use parameterized queries instead.
```

***

## Links

* **PyPI:** [pypi.org/project/qwed-mcp](https://pypi.org/project/qwed-mcp/)
* **GitHub:** [github.com/QWED-AI/qwed-mcp](https://github.com/QWED-AI/qwed-mcp)
* **Docker Hub (organization):** [hub.docker.com/orgs/qwedai/repositories](https://hub.docker.com/orgs/qwedai/repositories)
* **Docker Hub (QWED Verification):** [qwedai/qwed-verification](https://hub.docker.com/repository/docker/qwedai/qwed-verification/general)
* **Docker Hub (QWED MCP):** [qwedai/qwed-mcp](https://hub.docker.com/repository/docker/qwedai/qwed-mcp)
* **MCP Protocol:** [modelcontextprotocol.io](https://modelcontextprotocol.io)
* **QWED Core:** [QWED Verification Engine](/intro)


## Related topics

- [Agentic security guards for the QWED Python SDK](/sdks/guards.md)
- [MCP tools reference](/mcp/tools.md)
- [QWED MCP troubleshooting](/mcp/troubleshooting.md)
- [QWED Protocol releases: SDK versions and installs](/releases.md)
- [Verification Context specification](/specs/verification-context.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.