Agent Integration
Use the RiskModels API with your AI assistant of choice to perform quant research, graph residuals, and analyze hedge ratios—all from natural language.
Paste this into a fresh chat. The agent reads riskmodels.app, sets itself up for the conversation, and tells you what it can analyze. Nothing to install.
Settings → Connectors → Add custom connector, paste the URL (leave OAuth fields blank), then Connect. You sign in at riskmodels.app and approve once — no API key to handle, billing on your account.
Prefer a terminal, or need Codex / VS Code? npx -y riskmodels@latest install wires every client in one command.
Install the CLI globally, then let it auto-wire Claude Desktop, Cursor, Codex, and VS Code in one command.
riskmodels install prompts for your key (get one at riskmodels.app/get-key) and stores it in ~/.config/riskmodels/config.json.
Paste the Rules for AI prompt below so Cursor understands RiskModels field names automatically. Optionally add the MCP server for live inline tool calls inside the chat panel.
Add the RiskModels MCP server to your Claude Desktop config so Claude can fetch live risk data, compute hedge ratios, and generate plots autonomously.
Add the MCP server to your Zed assistant config. Zed auto-discovers available tools so you can query live risk data inline as you code. See MCP setup ↓
Cursor Rules for AI Prompt
Paste this into Project Settings → Rules for AI (or save as .cursorrules in your project root):
You are a RiskModels Analyst. Your goal is to help me perform quant research.
1. Use the RiskModels MCP server for discovery: `riskmodels_list_endpoints`,
`riskmodels_get_capability`, `riskmodels_get_schema` (see mcp/README.md).
2. For live data (metrics, batch portfolio, L3 series), call the REST API or use
`riskmodels-py` — the repo MCP server does not expose separate portfolio/decomposition tools.
3. When asked to "graph the residuals," fetch L3 decomposition or returns via
GET /api/l3-decomposition or GET /api/ticker-returns (or the Python SDK) and plot
explained-risk or residual columns per SEMANTIC_ALIASES.md.
4. For hedge ratios in user-facing tables, prefer semantic names: l3_market_hr,
l3_sector_hr, l3_subsector_hr (SDK); raw JSON may use l3_mkt_hr-style keys.
5. Refer to SEMANTIC_ALIASES.md in the workspace for math definitions.
If I ask: "Graph market residuals for META," fetch the appropriate time series from
the API or SDK and generate a Python plot.
MCP Server Setup
Connect by URL (no terminal, recommended)
In Claude Desktop or Cursor, open Settings → Connectors → Add custom connector and paste:
https://riskmodels.app/api/mcp/sse
Leave the OAuth Client ID / Secret fields blank, click Add, then Connect. You'll sign in at riskmodels.app and approve access once (OAuth 2.0 + PKCE — the client registers itself); the tools then load and metered calls bill your account. Nothing to install, and no API key to copy or store.
Hosted via the mcp-remote proxy (Bearer key)
Prefer a static API key instead of signing in? Add the endpoint through the mcp-remote proxy:
{
"mcpServers": {
"riskmodels": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://riskmodels.app/api/mcp/sse"],
"env": { "AUTHORIZATION": "Bearer <your key>" }
}
}
}
Get a key at /get-key. Discovery tools are free; data tools bill per underlying REST route.
Local — build from source (developer)
If you're hacking on the server itself, add to .cursor/mcp.json (or your Claude Desktop / Zed config):
# Build the MCP server first (required before first use)
cd mcp && npm ci && npm run build
{
"mcpServers": {
"riskmodels-api": {
"command": "node",
"args": ["/absolute/path/to/RiskModels_API/mcp/dist/index.js"]
}
}
}
The args path must point to mcp/dist/index.js — the compiled output. If dist/ does not exist, run the build command above.
Restart your editor after saving. See the MCP server README for full setup.
Compose & chain
RiskModels is one specialized link in an agent's tool chain. Outputs are stable JSON designed to feed the next call — yours or another provider's.
A typical risk-then-act flow:
-
Decompose a position into its four factor layers and ETF hedge map.
curl -X POST https://riskmodels.app/api/decompose \ -H "Authorization: Bearer $RISKMODELS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"ticker":"NVDA"}'The response
hedgeobject is{ ETF: ratio }— e.g.{ "SPY": 0.85, "XLK": 0.15 }. Those ETF tickers and ratios are the join key to the next step. -
Scale to a dollar position. Feed the same ticker + your notional to
riskmodels_hedge_position(MCP) orPOST /api/hedge-basket/{ticker}to turn ratios into share/dollar legs. -
Roll up to a portfolio. Pass a holdings list to
POST /api/portfolio/risk-snapshotto get variance decomposition and diversification metrics across names — then hand the aggregated hedge legs to an execution / brokerage API to actually trade them.
Why this chains cleanly:
- Stable schemas. Every response shape is published at
/openapi.jsonand the per-response JSON schemas (riskmodels_get_schema/riskmodels:///schemas/{path}). Validate before wiring a downstream call. - Citeable outputs.
_metadata.model_version+data_as_ofand_agent.request_idtravel with each result, so a downstream tool (or an auditor) can trace exactly which inputs produced an action. - Idempotent steps. Send an
Idempotency-Keyon POSTs so a retried chain step never double-charges or double-acts. - Cost & latency in-band.
_agent.cost_usdand_agent.latency_mslet an orchestrating agent budget a multi-call plan before running it.
Discover the full tool set in one fetch: /.well-known/agent-manifest.json. See For agents for the onboarding and trust overview.