sentinel-mcp-server 0.1.0

MCP server for Sentinel prediction markets — trade as an AI agent via Claude Desktop, Cursor, or Claude Code

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

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):

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

# 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:

{
  "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:

{
  "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.