# DeAlgo MCP Server

Runtime decision firewall for AI agents. Exposes the **CSC** engine (via the
`dealgo-portal` control layer) as a Model Context Protocol server so any
MCP-aware client — Claude Desktop, Claude Code, Cursor, custom agents — can
consult CSC before executing risky actions.

```
Claude / agent
      ↓
MCP tool: csc_check(...)
      ↓
dealgo-portal /api/csc/check  (Bearer dealgo_sk_live_…)
      ↓
CSC engine: reality · policy · throttle gates
      ↓
{ decision, action, reason, v2_bias, latency_ms }
```

## Tools

### `csc_check(feed, risk?, volatility?, confidence?, symbol?, source?, intent?, v2_aware=True)`

Primary tool. Score one signal/action against CSC. Returns

```json
{ "decision": "APPROVE" | "DELAY" | "DENY",
  "action":   "EXECUTE" | "WAIT" | "REJECT",
  "reason":   "...",
  "v2_bias":  -0.018,
  "stimulus_id": "stim_…",
  "latency_ms": 41 }
```

Proceed only on `APPROVE`. On `DELAY`, retry with backoff. On `DENY`, do
not retry — surface the `reason` to the user.

### `check_action(intent, action, actor_id, domain, environment, metadata)`

Backwards-compat shim. Maps the legacy governance payload onto `csc_check`
so existing demos and Claude Desktop configs keep working. Prefer
`csc_check` directly in new code.

## Resource

`governance://decisions/recent` — last 20 decisions logged for the
configured API key. Lets agents introspect their own history.

## Setup (recommended — published package)

1. **Install:**
   ```bash
   pip install dealgo-mcp
   ```
2. **Get a sandbox key** from your portal at <https://api.dealgo.io/keys>
   (or `https://api.dealgo.io/quickstart` for a one-click reveal). Use a
   `dealgo_sk_test_…` key for a no-meter sandbox, `dealgo_sk_live_…` for prod.
3. **Wire into Claude Desktop.** Merge this into the config:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
   ```json
   {
     "mcpServers": {
       "dealgo-csc": {
         "command": "dealgo-mcp",
         "env": {
           "DEALGO_API_KEY": "dealgo_sk_test_…",
           "DEALGO_API_URL": "https://api.dealgo.io"
         }
       }
     }
   }
   ```
4. **Restart Claude Desktop.** Then ask Claude:

   > "Use `csc_check` before doing anything risky."

   Every risky action will now consult `/v1/decide` and surface the verdict.

## Setup (local dev — from source)

```bash
git clone https://github.com/dealgo-systems/dealgo-mcp-server
cd dealgo-mcp-server
pip install -e .            # editable install — picks up changes immediately
```

Then point Claude Desktop config to the editable install (`"command": "dealgo-mcp"`
still works after `pip install -e .` — entry point is registered system-wide).

## Smoke test

```bash
DEALGO_API_KEY=dealgo_sk_test_... python smoke_test.py
```

Exercises all three CSC gates (reality, policy, throttle), the
backwards-compat shim, and the recent-decisions resource. Pass = CSC
governance is live over MCP.

## Configuration

| Env var          | Default                    | Required |
|------------------|----------------------------|----------|
| `DEALGO_API_KEY` | (none)                     | yes      |
| `DEALGO_API_URL` | `https://api.dealgo.io`    | no       |

Now Claude can call CSC before executing actions.