# scorton-mcp

Cloudflare Workers MCP server for behavioral cybersecurity and AI risk in financial workflows.

Built with the universal [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) and Cloudflare's [`agents`](https://developers.cloudflare.com/agents/) `McpAgent` runtime.

## What this server provides

### MCP tools
- `score_human_risk`
- `score_ai_risk`
- `score_workflow_risk`
- `run_ai_eval_summary`
- `generate_audit_snapshot`
- `health_check`

### MCP resources
- `scorton://policy-profile` — active scoring policy and thresholds.

All tool inputs are validated with **Zod** and outputs are machine-oriented JSON.

## Architecture

```text
src/
  config/        # app metadata + scoring thresholds
  mcp/           # ScortonMCP agent (tools + resources)
  schemas/       # Zod input/output schemas
  services/      # pure business logic / scoring
  utils/         # logger + structured errors
tests/           # node:test unit tests
```

### Runtime
- **Framework:** `@modelcontextprotocol/sdk` + `agents/mcp`
- **Hosting:** Cloudflare Workers + Durable Objects
- **Endpoint:** `https://<worker>.workers.dev/mcp`

## Quick start

### Prerequisites
- Node.js 18+
- Cloudflare account with Workers enabled
- `wrangler login`

### Local development

```bash
npm install
npm run dev
```

Server runs at `http://localhost:8788/mcp`.

Test with MCP Inspector:

```bash
npx @modelcontextprotocol/inspector@latest
# Open http://localhost:5173 and connect to http://localhost:8788/mcp
```

### Deploy to Cloudflare

1. Update `wrangler.jsonc` vars:
   - `MCP_URL` → your worker URL (e.g. `https://scorton-mcp.scortonlabs.workers.dev`)
   - `TEAM_DOMAIN` → your Access team (e.g. `https://scortonlabs.cloudflareaccess.com`)
   - `POLICY_AUD` → AUD tag from Zero Trust → Access → your application
2. Deploy:

```bash
npm run deploy
```

3. Connect clients to `https://scorton-mcp.scortonlabs.workers.dev/mcp`.

### Cloudflare Access (required for protected workers)

If the worker is behind a **self-hosted Access application**, set `TEAM_DOMAIN` and `POLICY_AUD` in `wrangler.jsonc` (or Worker dashboard vars). The worker validates the `Cf-Access-Jwt-Assertion` header on `/mcp` requests.

Find the AUD tag: Zero Trust → Access → Applications → your app → **AUD tag**.

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "scorton": {
      "command": "npx",
      "args": ["mcp-remote", "https://scorton-mcp.<your-subdomain>.workers.dev/mcp"]
    }
  }
}
```

**Cursor** — add as a remote MCP server with the same URL.

## Configuration

Scoring thresholds are set via Worker vars in `wrangler.jsonc`:

| Variable | Default | Purpose |
|----------|---------|---------|
| `RISK_HUMAN_BASELINE_THRESHOLD` | `0.2` | Human baseline deviation flag threshold |
| `RISK_AI_FAILURE_WEIGHT` | `0.5` | Weight of eval failures in AI risk score |
| `RISK_WORKFLOW_HIGH_VALUE_THRESHOLD` | `100000` | USD threshold for high-value workflow flag |

## Scripts

```bash
npm run dev        # wrangler dev (local Worker)
npm run deploy     # deploy to Cloudflare
npm run typecheck  # TypeScript checks
npm run test       # unit tests (services layer)
npm run cf-typegen # regenerate worker Env types
```

## Example tool payloads

### `score_human_risk`
```json
{
  "actorId": "user-42",
  "baselineDeviation": 0.61,
  "velocityAnomalyScore": 0.88,
  "navigationAnomalyScore": 0.74,
  "repeatedEditsCount": 7,
  "sourceChannel": "new-device",
  "workflowContext": "wire-transfer-approval"
}
```

### `score_ai_risk`
```json
{
  "modelId": "llm-payments-v3",
  "evalFailureRate": 0.31,
  "useCaseCriticality": "mission-critical",
  "complianceCategory": "aml",
  "productionExposure": "full",
  "recentIncidents": 2
}
```

### `score_workflow_risk`
```json
{
  "workflowId": "ap-invoice-2026-0009",
  "sequenceAnomalyScore": 0.67,
  "actorRole": "approver",
  "transactionValueUsd": 240000,
  "vendorOrPaymentChangeSignal": true,
  "changeWindowMinutes": 22
}
```

## Optional: Cloudflare Access MCP portal

Register this server in [Cloudflare Access AI controls](https://developers.cloudflare.com/cloudflare-one/access-controls/ai-controls/mcp-portals/) to add OAuth governance and a managed portal for your team.

## Migration from v1 (mcp-use / Dokploy)

v1 used `mcp-use` on Node.js + Docker. v2 runs on Cloudflare Workers with the standard MCP SDK. Tool names, schemas, and scoring logic are unchanged — only the transport/runtime changed.