RiskState MCP Server

MCP server for RiskState — pre-trade risk permissions for BTC/USD and ETH/USD. Spot, perpetual futures (perps), and DeFi borrowing aware.

Your system asks: **"How much can I risk right now?"**RiskState answers with: policy level, max exposure, leverage limits, blocked actions — computed from 30+ real-time signals.

What it does

Wraps the RiskState /v1/risk-state API as an MCP tool. One tool: get_risk_policy.

Field	Description
policy_level	5 levels: BLOCK_SURVIVAL, BLOCK_DEFENSIVE, CAUTIOUS, GREEN_SELECTIVE, GREEN_EXPANSION
max_size_pct	Maximum position size as % of portfolio (0-100)
leverage_max	Maximum allowed leverage multiplier
allowed_actions	What the agent CAN do at this policy level
blocked_actions	What the agent CANNOT do
confidence_score	Signal agreement x data quality (0-1)

The API aggregates 9+ real-time data sources server-side. See API docs for details.

What this wrapper does (and doesn't)

This is a thin wrapper — it translates MCP tool calls into REST API requests to POST /v1/risk-state and returns the response. All computation (scoring, policy engine, data ingestion) happens server-side.

This wrapper adds:

• MCP protocol compliance (stdio transport for Claude Desktop/Code)
• Input validation via Zod schemas
• Human-readable policy summary prepended to responses
• Specific error messages (auth, rate limit, timeout) for agent recovery

This wrapper does NOT:

• Cache responses (the API has 60s server-side cache)
• Perform any scoring or computation locally
• Guarantee response schema stability (follows API versioning)

Installation

npm install @riskstate/mcp-server

Configuration

Environment Variables

Variable	Required	Description
RISKSTATE_API_KEY	Yes	API key from riskstate.ai (free during beta)
RISKSTATE_API_URL	No	Custom API base URL (default: https://api.riskstate.ai)

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json:

{ "mcpServers": { "riskstate": { "command": "npx", "args": ["-p", "@riskstate/mcp-server", "riskstate-mcp"], "env": { "RISKSTATE_API_KEY": "your-api-key" } } } }

Claude Code

claude mcp add riskstate -- npx -p @riskstate/mcp-server riskstate-mcp

Set the API key in your environment:

export RISKSTATE_API_KEY=your-api-key

Global install (alternative)

npm install -g @riskstate/mcp-server riskstate-mcp # starts MCP server on stdio

Usage

The server exposes one tool: get_risk_policy

Parameters

Parameter	Type	Required	Description
asset	"BTC" | "ETH"	Yes	Asset to analyze
wallet_address	string	No	DeFi wallet for on-chain position data
protocol	"spark" | "aave"	No	Lending protocol (default: spark)
include_details	boolean	No	Include full breakdown (subscores, macro, risk flags)

Example Response

{ "exposure_policy": { "policy_level": "CAUTIOUS", "max_size_pct": 35, "leverage_max": 1.5, "allowed_actions": ["DCA", "WAIT", "SPOT_LONG_CONFIRMED"], "blocked_actions": ["LEVERAGE_GT_2X", "NEW_POSITIONS_UNCONFIRMED"] }, "classification": { "cycle_phase": "MID", "market_regime": "RANGE", "macro_regime": "NEUTRAL", "direction": "SIDEWAYS" }, "auditability": { "composite_score": 52, "confidence_score": 0.72, "policy_hash": "a3f8c2...", "ttl_seconds": 60 } }

How Agents Should Use This

Call get_risk_policy before every trade:

1. If policy_level starts with BLOCK → do not open new positions
2. Use max_size_pct to cap position sizing
3. Check blocked_actions before executing
4. Re-query after ttl_seconds (60s cache)

Limitations

• v1 scope: BTC/USD and ETH/USD only (USD-denominated assessment). More assets planned.
• Markets: Spot, perpetual futures, and DeFi borrowing. Same response — interpretation differs by market (see API docs).
• Protocols: Spark and Aave V3 only for DeFi position data.
• Rate limit: 60 requests/minute per API key.
• Latency: ~1-3s per request (9+ upstream data source aggregation).
• Tested with: Claude Desktop, Claude Code. Should work with any MCP-compatible client.

Links

• Landing page: riskstate.ai
• API docs: riskstate.ai/docs/api
• SKILL.md: agentskills.io

License

MIT