# Sentinel MCP Server

Expose Sentinel's prediction market API as MCP tools, allowing any MCP-compatible AI (Claude Desktop, Cursor, Claude Code) to trade as a registered agent.

## Architecture

```
AI Client (Claude Desktop / Cursor)
    │  MCP Protocol (stdio)
    ▼
Sentinel MCP Server (Python)
    │  HTTP + Ed25519 headers
    ▼
Sentinel Backend (Spring Boot)
    - Policy Gate (7 checks)
    - LMSR Engine
    - Audit Trail
```

This is a thin adapter — **not** a new backend. All auth, policy enforcement, and audit logging is handled by the existing Spring Boot backend.

## Prerequisites

1. Python 3.11+
2. Sentinel backend running on `http://localhost:8080`

That's it. The MCP server auto-generates Ed25519 keys on first run.

## Setup

```bash
cd apps/mcp-server
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

pip install -e .
```

Copy `.env.example` to `.env` (only needs the API URL):

```bash
cp .env.example .env
```

## First Run — Agent Identity

On first startup the MCP server automatically:

1. **Generates an Ed25519 keypair** and saves it to `~/.sentinel-agent/identity.json`
2. Exposes the `whoami` tool so the AI client can show its public key

### Registration Flow

Registration is an **operator action**, not a self-service operation:

1. AI client calls `whoami` → gets its public key
2. AI presents the public key to the operator
3. **Operator** registers the agent in the Sentinel console using that public key
4. Operator tells the AI its assigned agent ID (UUID)
5. AI client calls `set_agent_id(agent_id="...")` to save it locally
6. **Operator** approves the agent and issues TRADE capabilities via the console
7. Agent can now trade

## Development

```bash
# MCP Inspector (browser-based tool tester)
mcp dev src/sentinel_mcp/server.py

# Direct stdio mode
mcp run src/sentinel_mcp/server.py
```

## Claude Desktop Configuration

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sentinel": {
      "command": "python",
      "args": ["-m", "sentinel_mcp.server"],
      "cwd": "C:/path/to/apps/mcp-server",
      "env": {
        "SENTINEL_API_URL": "http://localhost:8080/api/v1"
      }
    }
  }
}
```

No agent keys or IDs needed in the config — identity is managed automatically.

## Available Tools

| Tool | Description | Auth |
|------|-------------|------|
| `whoami` | Show agent public key and registration status | None |
| `set_agent_id` | Save the operator-assigned agent ID | None |
| `list_markets` | List markets with optional status filter | Agent |
| `get_market` | Get full market details | Agent |
| `get_market_trades` | Get recent trades on a market | Agent |
| `place_trade` | Buy YES/NO shares (7-check policy gate) | Agent |
| `get_position` | Check position in a market | Agent |
| `my_status` | Check agent profile and capabilities | Agent |
| `kill_switch_status` | Check if platform is halted | Public |

## Identity Storage

Agent identity is stored at `~/.sentinel-agent/identity.json`:

```json
{
  "agent_id": "uuid-assigned-by-operator",
  "public_key": "64-char-hex",
  "private_key": "128-char-hex",
  "created_at": "2026-03-11T12:00:00Z"
}
```

The private key file is restricted to owner-only permissions (`chmod 600`) on Unix systems.

## Safety Guarantees

The MCP server preserves all Sentinel safety guarantees:

- **Same authentication** — Ed25519 signatures on every request
- **Same 7-check policy gate** — kill switch, agent status, capabilities, rate limits, position limits, trade size, market state
- **Same audit trail** — every trade logged as an immutable DecisionPacket
- **Same kill switch** — blocks MCP trades identically to REST trades
- **Operator controls registration** — agents cannot self-register; the operator registers, approves, and grants capabilities

The operator cannot distinguish MCP trades from REST trades in the audit log.
