likidodefi/riskstate-mcp

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 MCP
server (Streamable HTTP) with a free public tier:
Add it as a custom connector in Claude or
ChatGPT, then just ask what the risk
state of BTC is. It exposes three read-only tools — get_risk_state,
get_market_structure, get_playbook_status — covering all three engines, and
is listed on the official MCP registry as ai.riskstate/mcp.
Responses are the free public summary: the same altitude as the public
visualizer. policy_hash, composite subscores, positioning and macro detail
need a key.
**2. This package — stdio, keyed, full response.** Use it when you want the
complete audited payload in a local agent, or to pin a version in your own
toolchain. It needs a RISKSTATE_API_KEY and returns everything your key is
entitled to. That is what the rest of this README covers.
Tools
Four read-only tools, one per question you might ask before a trade:
| Tool | Answers | Endpoint | Key |
|------|---------|----------|-----|
| get_risk_policy | *How much exposure is allowed?* | POST /v1/risk-state | yes |
| get_market_structure | *Are we near a structural inflection?* | POST /v1/market-structure | yes |
| get_playbook_status | *Is a setup actionable right now?* | GET /api/playbook-data | no |
| check_trade | *Would THIS position be allowed?* | POST /v2/portfolio-risk-state | yes |
get_risk_policy returns:
| 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) |
check_trade evaluates a hypothetical book — send the position you are
considering **plus anything you already hold**, since the caps are
portfolio-aware. It returns per position whether it is allowed, the size cap in
percent 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 conditions
match, no engine vetoed it, **and** it is not in alert cooldown. Setups that
match but already alerted are counted separately, so an agent polling this tool
does 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 there
will not be. The premise of RiskState is that the system being governed cannot
move its own limits. Every decision is hashed (policy_hash) so it can be
audited afterwards against the inputs that produced it; a tool that let the
caller rewrite the policy would make that hash meaningless and the audit trail
decorative.
So the lifecycle here deliberately lives on one side: the engine computes, the