RiskState MCP Server

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.

Two ways to use RiskState over MCP

1. Remote connector — no install, no API key. RiskState runs a hosted MCPserver (Streamable HTTP) with a free public tier:

https://api.riskstate.ai/mcp

Add it as a custom connector in Claude orChatGPT, then just ask what the riskstate of BTC is. It exposes three read-only tools — get_risk_state,get_market_structure, get_playbook_status — covering all three engines, andis listed on the official MCP registry as ai.riskstate/mcp.

Responses are the free public summary: the same altitude as the publicvisualizer. policy_hash, composite subscores, positioning and macro detailneed a key.

2. This package — stdio, keyed, full response. Use it when you want thecomplete audited payload in a local agent, or to pin a version in your owntoolchain. It needs a RISKSTATE_API_KEY and returns everything your key isentitled to. That is what the rest of this README covers.

Tools

Four read-only tools, one per question you might ask before a trade:

get_risk_policy returns:

check_trade evaluates a hypothetical book — send the position you areconsidering plus anything you already hold, since the caps areportfolio-aware. It returns per position whether it is allowed, the size cap inpercent and dollars, and reason_codes when it is not. Those are blocking;advisories are informational and do not affect allowed. It places no orders.

get_playbook_status reports a setup as actionable only when its conditionsmatch, no engine vetoed it, and it is not in alert cooldown. Setups thatmatch but already alerted are counted separately, so an agent polling this tooldoes not act on the same signal twice.

Why there are no write tools

There is no update_policy, no set_limit, no exception management — and therewill not be. The premise of RiskState is that the system being governed cannotmove its own limits. Every decision is hashed (policy_hash) so it can beaudited afterwards against the inputs that produced it; a tool that let thecaller rewrite the policy would make that hash meaningless and the audit traildecorative.

So the lifecycle here deliberately lives on one side: the engine computes, theagent reads and complies. check_trade is the closest thing to a dynamicper-trade operation, and it is still read-only — it answers "would this beallowed", never "allow this".

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

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 four tools are listed above. get_risk_policy takes:

Parameters

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)

For a sized position, check_trade collapses steps 2-3 into one call: send theposition you intend to open along with what you already hold, and read allowedplus reason_codes. Prefer it over re-deriving the cap yourself, since the capsare portfolio-aware and a position that passes in isolation can still breachconcentration once aggregated.

get_market_structure and get_playbook_status are context, not permission.Neither one authorises a trade — only the risk policy does. Use them to decidewhether a trade is worth proposing, then get_risk_policy / check_trade tolearn how much of it you are allowed.

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