RiskState MCP server
Commit Sep 10, 2026Provides real-time crypto risk permissions, market structure analysis, and trading playbook status for BTC and ETH.
Also known as Riskstate/mcp, mcp
- Stars
- 1
- Tools
- 10
- Downloads, 30 days
- —
- Latest version
- 1.0.1
- Last commit
- Sep 10, 2026
- License
- MIT
What is RiskState MCP?
RiskState provides real-time crypto risk permissions, market structure analysis, and trading playbook status for BTC and ETH. It exposes 10 tools, such as get_risk_policy, get_market_structure, get_playbook_status.
Summary generated from the project's README
About RiskState MCP server
Managing cryptocurrency exposure and trade permissions for BTC and ETH is what RiskState enables for automated trading agents and developers. By integrating this server into clients like Claude Desktop or Claude Code, users can access real-time risk assessments that cover spot markets, perpetual futures, and DeFi borrowing on protocols like Aave and Spark. The system calculates limits based on over 30 real-time signals to determine if a specific trade is permitted within a defined portfolio.
Users can connect via a hosted remote endpoint that requires no installation or API key for basic public summaries, or they can run a local version using stdio for full audited data. The local setup requires a RISKSTATE_API_KEY to access detailed information such as policy hashes, composite subscores, and macro details. The server provides read-only tools including get_risk_policy, get_market_structure, get_playbook_status, and check_trade to ensure that the governing engine remains separate from the agent executing the trades.
What you can do with it
- 1Verify trade permissionAsk the agent to check if a specific position would be allowed given current portfolio holdings.
- 2Validate trading setupsCheck if a specific trading playbook setup is currently actionable and not in a cooldown period.
Written from the project's README. Every use case is checked against a quote from it.
How to install RiskState MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall RiskState MCP in Claude Code
$ claude mcp add --transport http mcp https://api.riskstate.ai/mcpInstall RiskState MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"url": "https://api.riskstate.ai/mcp"
}
}
}Install RiskState MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "http",
"url": "https://api.riskstate.ai/mcp"
}
}
}Install RiskState MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"http","url":"https://api.riskstate.ai/mcp"}'Install RiskState MCP in Codex
$ codex mcp add mcp --url https://api.riskstate.ai/mcpInstall RiskState MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] url = "https://api.riskstate.ai/mcp"
Install RiskState MCP in Gemini CLI
$ gemini mcp add -s user --transport http mcp https://api.riskstate.ai/mcpInstall RiskState MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"url": "https://api.riskstate.ai/mcp",
"type": "http"
}
}
}RiskState MCP tools 10
Detected from the READMEget_risk_policyget_market_structureget_playbook_statuscheck_tradepolicy_levelmax_size_pctleverage_maxallowed_actionsblocked_actionsconfidence_score
Configuration
RISKSTATE_API_KEY
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableriskstate/mcp is public and reachablegithub.com/riskstate/mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-10github.com/riskstate/mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model10 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeinitialize answered with protocol 2025-06-18 in 827 msPass
README
View on GitHubRiskState 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 MCP server (Streamable HTTP) with a free public tier:
https://api.riskstate.ai/mcp
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
agent reads and complies. check_trade is the closest thing to a dynamic
per-trade operation, and it is still read-only — it answers "would this be
allowed", 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
| 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 four tools are listed above. get_risk_policy takes:
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:
- If
policy_levelstarts withBLOCK→ do not open new positions - Use
max_size_pctto cap position sizing - Check
blocked_actionsbefore executing - Re-query after
ttl_seconds(60s cache)
For a sized position, check_trade collapses steps 2-3 into one call: send the
position you intend to open along with what you already hold, and read allowed
plus reason_codes. Prefer it over re-deriving the cap yourself, since the caps
are portfolio-aware and a position that passes in isolation can still breach
concentration 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 decide
whether a trade is worth proposing, then get_risk_policy / check_trade to
learn 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
RiskState MCP questions
How do I add RiskState MCP to Claude Code?
Run claude mcp add --transport http mcp https://api.riskstate.ai/mcp in your terminal. Add --scope user to make it available in every project.
How do I add RiskState MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does RiskState MCP provide?
It exposes 10 tools, including get_risk_policy, get_market_structure, get_playbook_status, check_trade, policy_level.
Can I use RiskState without an API key?
Yes, you can use the hosted remote connector via a free public tier which provides a summary of the risk state.
Does this server allow me to execute trades?
No, the server is read-only and does not include any write tools for updating policies or placing orders.
What assets are currently supported?
The current version is limited to BTC/USD and ETH/USD assessments.
How does the check_trade tool work?
It evaluates a hypothetical position against your existing holdings to determine if it is allowed based on portfolio-aware caps.