# PRAQTOR MCP-S

**AI Agent Security Scanner for MCP Servers**

[![PyPI version](https://img.shields.io/pypi/v/praqtor-mcp.svg)](https://pypi.org/project/praqtor-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/praqtor-mcp.svg)](https://pypi.org/project/praqtor-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Scan live MCP servers and configuration files for security vulnerabilities. 8 detection engines, attack chain analysis, zero false positives.

## Installation

```bash
pip install praqtor-mcp
```

## Quick Start

```bash
# Set your API key
export PRAQTOR_API_KEY=your-api-key

# Scan a live MCP server by URL
praqtor-mcp scan-url https://mcp.example.com/sse

# Scan a config file
praqtor-mcp scan config.json

# Output as JSON
praqtor-mcp scan-url https://mcp.example.com/sse --format json

# Output as SARIF (for GitHub Advanced Security)
praqtor-mcp scan-url https://mcp.example.com/sse --format sarif > results.sarif
```

## How It Works

**URL Scan** — Point at any live MCP server. PRAQTOR connects via SSE or Streamable HTTP, discovers tools automatically, then runs all 8 security engines against the real tool definitions.

**Config Scan** — Pass your `mcpServers` JSON configuration. PRAQTOR analyzes the server definitions, tool schemas, and cross-server interactions.

## Detection Engines

| Engine | Code | What It Detects |
|--------|------|-----------------|
| Secret & Data Exposure | SDE | API keys, tokens, credentials in configs |
| Semantic Threat Analysis | STA | Tool poisoning, description manipulation |
| Schema Integrity Monitor | SIM | Schema drift, type confusion attacks |
| Package Provenance | PPV | Supply chain risks, unverified packages |
| Cross-Origin Influence | COI | Cross-server trust violations |
| Data Flow Path Analysis | DFP | Sensitive data flowing between tools |
| Permission Alignment | CPA | Over-permissioned tool capabilities |
| Attack Surface Hardening | ASH | Injection surfaces, SSRF, command injection |

Plus **ENABLES** — attack chain wiring that connects findings across engines.

## Commands

### `scan-url` — Scan a Live MCP Server

```bash
praqtor-mcp scan-url https://mcp.example.com/sse
```

Connects to the MCP server, performs protocol handshake, discovers all tools via `tools/list`, and runs the full 8-engine scan.

### `scan` — Scan a Config File

```bash
praqtor-mcp scan my-mcp-config.json
```

Analyzes an MCP configuration file (the same format used by Claude Desktop, Cursor, etc.).

### `health` — Check API Status

```bash
praqtor-mcp health
```

### Output Formats

| Format | Flag | Use Case |
|--------|------|----------|
| Text | `--format text` | Terminal output with colors (default) |
| JSON | `--format json` | Programmatic consumption, CI/CD |
| SARIF | `--format sarif` | GitHub Advanced Security integration |

### Filtering

```bash
# Only show critical findings
praqtor-mcp scan-url https://mcp.example.com/sse --severity critical

# Limit output
praqtor-mcp scan-url https://mcp.example.com/sse --limit 10
```

## CI/CD Integration

### GitHub Actions

```yaml
- name: Scan MCP Config
  run: |
    pip install praqtor-mcp
    praqtor-mcp scan mcp-config.json --format sarif > praqtor-results.sarif
  env:
    PRAQTOR_API_KEY: ${{ secrets.PRAQTOR_API_KEY }}

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: praqtor-results.sarif
```

### Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Passed — no critical or high findings |
| 1 | Warning — high severity findings detected |
| 2 | Failed — critical findings detected |

## Configuration

Set credentials via environment variables or command-line flags:

```bash
# Environment variables (recommended)
export PRAQTOR_API_URL=https://praqtormcp.fly.dev
export PRAQTOR_API_KEY=your-api-key

# Or use flags
praqtor-mcp scan-url https://example.com/sse --api-url https://praqtormcp.fly.dev --api-key YOUR_KEY
```

## API

PRAQTOR MCP-S also provides a REST API for programmatic access:

```bash
curl -X POST https://praqtormcp.fly.dev/api/v1/scan/url \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://mcp.example.com/sse"}'
```

Full API docs: [https://praqtormcp.fly.dev/api](https://praqtormcp.fly.dev/api)

## License

MIT
