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.

Fastest — no terminal, use it in your AI chat

Try it now (this chat — no install)

Works in ChatGPT, Claude, Cursor, Grok, Gemini (web), or any model that can fetch URLs. The agent reads /llms.txt and must make a live REST call — not a persistent MCP connector.

Fetch https://riskmodels.app/llms.txt. Then GET https://riskmodels.app/api/metrics/AAPL and GET https://riskmodels.app/api/metrics/NVDA using the Bearer key from that file (or POST /api/auth/provision-free). Quote l3 residual explained-risk and the L3 hedge ratios from the JSON. Do not answer from training data.Copy

Keep it (Claude Desktop / Cursor — persistent MCP)

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.

https://riskmodels.app/api/mcp/sseCopy

After Connect, paste this so the agent pulls live numbers (not the catalog):

Call riskmodels_compare with tickers ["AAPL","NVDA"]. Then call riskmodels_decompose on AAPL and on NVDA. Quote residual explained-risk and the L3 hedge ratios from the tool results. Do not answer from training data. Do not call riskmodels_list_endpoints unless I ask which REST routes exist.Copy

Prefer a terminal, or need Codex / VS Code? npx -y riskmodels@latest install wires every client in one command.

ChatGPT — persistent MCP (Developer Mode)

ChatGPT does not expose RiskModels through the built-in Finances / Schwab connector — that is a separate data source. To add RiskModels as its own MCP app: Settings → Apps & Connectors → Advanced settings → enable Developer mode, then Apps & Connectors → Create, paste the URL below, choose OAuth, and sign in at riskmodels.app when prompted. Requires ChatGPT Plus or above (web). Discovery manifest: /.well-known/mcp.json.

https://riskmodels.app/api/mcp/sseCopy

Portfolio + Schwab in one chat? Keep Finances for holdings, then paste tickers/weights here and ask ChatGPT to call RiskModels REST (or use the in-chat prompt above). See ChatGPT + holdings ↓.

Grok — persistent MCP (Connectors)

Open grok.com/connectors → New Connector → Custom, paste the URL below, and complete OAuth sign-in at riskmodels.app. Grok discovers tools from the server automatically (Streamable HTTP). No Developer Mode toggle — the connector UI is public on Grok web, iOS, and Android.

https://riskmodels.app/api/mcp/sseCopy

Details: Grok setup ↓ · xAI docs: Connectors

Gemini — depends on surface

gemini.google.com (consumer chat): no custom MCP UI — use the in-chat prompt above (/llms.txt + REST). Gemini CLI / Antigravity: terminal MCP with OAuth (gemini mcp add …). Gemini Enterprise: admin registers this server as a Custom MCP data store in Google Cloud (Streamable HTTP + OAuth).

Details: Gemini setup ↓

Developer — terminal install

Any Terminal

Install the CLI globally, then let it auto-wire Claude Desktop, Cursor, Codex, and VS Code in one command.

npm install -g riskmodels@latestCopy

riskmodels installCopy

riskmodels install prompts for your key (get one at riskmodels.app/get-key) and stores it in ~/.config/riskmodels/config.json.

Enhanced — Native AI tool calls via MCP

Cursor

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.

Claude Desktop

Add the RiskModels MCP server to your Claude Desktop config so Claude can fetch live risk data, compute hedge ratios, and generate plots autonomously.

Zed

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 ↓

Grok

Add a custom MCP connector at grok.com/connectors — OAuth sign-in, no Developer Mode. See Grok setup ↓

Gemini

Consumer web chat: use /llms.txt in-session. Persistent MCP: Gemini CLI or Gemini Enterprise admin setup. See Gemini 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.

ChatGPT (Developer Mode)

ChatGPT supports custom remote MCP servers, but the UI is hidden until Developer mode is on:

1. Settings → Apps & Connectors → Advanced settings → enable Developer mode (Plus / Pro / Business / Enterprise / Edu; web only).
2. Apps & Connectors → Create (button appears after step 1).
3. Connector URL: https://riskmodels.app/api/mcp/sse
4. Choose OAuth (not a static API key). Complete sign-in at riskmodels.app when prompted.
5. Enable the tools you want (e.g. riskmodels_decompose, riskmodels_get_lstar, riskmodels_analyze_portfolio).

Machine-readable discovery: /.well-known/mcp.json · OAuth metadata: /.well-known/oauth-protected-resource.

Not the same as ChatGPT Finances. The Schwab / Finances connector only sees brokerage holdings. RiskModels is a separate MCP app for factor decomposition and hedge ratios.

ChatGPT + brokerage holdings (Finances + RiskModels)

When ChatGPT already has your Schwab book via Finances, you do not need RiskModels MCP in the same turn — combine sources in one chat:

1. Ask ChatGPT to list your holdings (tickers + weights or dollar notionals from Finances).
2. Paste: "Use https://riskmodels.app/llms.txt to set up RiskModels REST for this chat, then analyze factor exposure and concentration for these holdings: …"
3. For a full ~3k-name book, get a personal key at /get-key and paste it once (or use Developer Mode MCP above for persistent tools).

Example tickers ChatGPT may already see: VTI, GOOG, MS, AMZN, IEMG, NFLX. RiskModels returns L1/L2/L3 explained risk and ETF hedge ratios per name; aggregate with POST /api/portfolio/risk-snapshot when you have weights.

Grok (Connectors)

Grok ships a first-class Bring Your Own MCP flow — no hidden Developer Mode:

1. Open grok.com/connectors.
2. Click New Connector → Custom.
3. MCP server URL: https://riskmodels.app/api/mcp/sse
4. Complete OAuth sign-in at riskmodels.app when prompted.

Grok discovers tools from the server and exposes them in chat alongside built-in connectors (Gmail, Drive, GitHub, etc.). The server must be reachable on the public internet (RiskModels hosted endpoint satisfies this). xAI docs: Connectors · Remote MCP tools (API/SDK path for developers).

Gemini

Google exposes three different surfaces — pick the one you actually use:

Consumer chat (gemini.google.com) — no Settings → Connectors flow for custom MCP today. Use the in-chat prompt at the top of this page (/llms.txt + REST) for one-session analysis, or paste holdings and ask Gemini to call the API with a key from /get-key.

Gemini CLI / Antigravity (terminal) — MCP lives in the CLI, not the consumer web app:

gemini mcp add --transport http riskmodels https://riskmodels.app/api/mcp/sse

Start a session and run /mcp auth riskmodels to complete OAuth in the browser. Alternatively add to ~/.gemini/settings.json under mcpServers with httpUrl pointing at the URL above. Google is migrating free-tier CLI users toward Antigravity — the same Streamable HTTP URL and OAuth pattern apply there.

Gemini Enterprise (Google Cloud admin) — register RiskModels as a Custom MCP Server data store in the Google Cloud console (setup guide). Requirements:

Gemini Enterprise preview supports Streamable HTTP only (matches our endpoint). Unlike Claude/Cursor/Grok, Enterprise typically expects a pre-registered OAuth client (Client ID + Secret) rather than dynamic registration — register a client via POST /api/oauth/register or contact support for a team OAuth app, then paste the credentials into the Cloud console. End users authorize the connector from the Gemini Enterprise chat UI after an admin attaches the data 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:

1. 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 hedge object is { ETF: ratio } — e.g. { "SPY": 0.85, "XLK": 0.15 }. Those ETF tickers and ratios are the join key to the next step.

2. Scale to a dollar position. Feed the same ticker + your notional to riskmodels_hedge_position (MCP) or POST /api/hedge-basket/{ticker} to turn ratios into share/dollar legs.

3. Roll up to a portfolio. Pass a holdings list to POST /api/portfolio/risk-snapshot to 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.json and the per-response JSON schemas (riskmodels_get_schema / riskmodels:///schemas/{path}). Validate before wiring a downstream call.
• Citeable outputs. _metadata.model_version + data_as_of and _agent.request_id travel with each result, so a downstream tool (or an auditor) can trace exactly which inputs produced an action.
• Idempotent steps. Send an Idempotency-Key on POSTs so a retried chain step never double-charges or double-acts.
• Cost & latency in-band. _agent.cost_usd and _agent.latency_ms let 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.

Related