Documentation

Horizon Risk

Multi-factor risk attribution, portfolio analysis, and PDF report generation — accessible via REST API and MCP for Claude Desktop and Claude Code.

Quick Start

Get up and running in 3 steps.

Get an API key

Horizon is launching soon. Join our waitlist to get early access and an API key.

Add the MCP server

Claude Desktop — add to your config file:

claude_desktop_config.json

{
  "mcpServers": {
    "horizon-risk": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://horizon-mcp.simudyne.com/mcp",
        "--header",
        "X-API-Key: YOUR_API_KEY"
      ],
      "timeout": 300000
    }
  }
}

Claude Code — run this command:

terminal

claude mcp add horizon-risk \
  --transport http \
  https://horizon-mcp.simudyne.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"

Try it

Restart Claude Desktop (or start a new Claude Code session) and ask:

“Use Horizon Risk to analyze a portfolio with: AAPL 10%, MSFT 8%, GOOGL 7%, AMZN 7%, META 6%, NVDA 6%, TSLA 5%, JPM 5%, JNJ 5%, V 5%, PG 4%, UNH 4%, HD 4%, MA 4%, BAC 3%, XOM 3%, PFE 3%, COST 3%, ABBV 3%, CRM 3%, DIS 2%”

Claude will call run_analysis and return a summary of your portfolio's risk attribution. From there you can ask follow-up questions:

“What's the PnL decomposition by factor?”
“Show me the drawdown analysis”
“How does selection vs sizing break down?”
“Generate a risk report”

Minimum 20 symbols required

The cross-sectional factor model requires at least 20 unique symbols in your portfolio to estimate factor returns reliably. Portfolios with fewer symbols will return an error. You can include additional symbols in the universe using the symbols parameter even if they are not in your portfolio weights.

Overview

Horizon Risk runs a Barra-style multi-factor model on your portfolio and decomposes returns into market, sector, region, style, and statistical factor contributions. It then generates a professional PDF report with LLM-powered narrative insights.

You can interact with Horizon in two ways:

MCP — connect Claude Desktop or Claude Code to the Horizon MCP server and use natural language to analyse portfolios
REST API — call the endpoints directly from any language or tool

Authentication

All authenticated endpoints require an API key passed as the X-Api-Key header. API keys follow the format pk_live_ followed by 32 hex characters.

Contact your administrator or visit the Horizon dashboard to create an API key.

MCP Integration

The Horizon MCP server lets Claude Desktop and Claude Code call risk analysis tools directly. Set up takes under a minute.

See the Quick Start above for setup instructions for both Claude Desktop and Claude Code. The timeout is set to 5 minutes (300,000 ms) because the risk pipeline processes two years of market data and can take up to a few minutes for larger portfolios.

MCP Tools

The MCP server exposes 9 tools. Start with run_analysis to run the pipeline — it returns a session_id you pass to the other tools for instant drilldowns without re-running the pipeline.

run_analysis

Run the full risk pipeline on a portfolio. Returns summary metrics and a session_id for drilldowns. Requires at least 20 unique symbols.

Args: portfolio_weights, symbols?

get_pnl_decomposition

Factor-level P&L attribution broken down by market, sector, region, style, statistical, and idiosyncratic.

Args: session_id

get_drawdown_analysis

Maximum drawdown and the full drawdown time series.

Args: session_id

get_selection_sizing

Decomposes idiosyncratic returns into selection, sizing, and diversification contributions.

Args: session_id

get_factor_exposures

Fundamental and statistical factor exposure time series.

Args: session_id

get_risk_decomposition

Attribution variance and confidence intervals for each factor.

Args: session_id

generate_narrative_insights

LLM-generated 2-3 paragraph professional portfolio commentary.

Args: session_id

generate_report

Generate a PDF report from cached analysis or raw portfolio weights.

Args: session_id? | portfolio_weights?, template?

list_templates

List available report templates (executive, detailed, visual, modern).

Args: none

Workflow

A typical conversation with Claude using Horizon looks like this:

You

Analyse a portfolio: 30% AAPL, 25% MSFT, 20% GOOGL, 10% AMZN, 5% META, 5% NVDA, 5% TSLA...

Claude

Calls run_analysis → returns summary: cumulative return, Sharpe, max drawdown, top/bottom factors

You

What's driving the drawdown?

Claude

Calls get_drawdown_analysis and get_pnl_decomposition → explains which factors caused the worst drawdown periods

You

Generate a report

Claude

Calls generate_report → returns a signed URL to download the PDF

API Reference

Base URL: https://horizon-api.simudyne.com

All authenticated endpoints require the X-Api-Key header.

Analysis Endpoints

Method	Path	Description	Auth
POST	/analysis	Run pipeline, cache results, return summary + session_id	API key
GET	/analysis/{id}/pnl	Factor-level P&L attribution (daily + summary)	API key
GET	/analysis/{id}/drawdown	Max drawdown + drawdown time series	API key
GET	/analysis/{id}/selection-sizing	Selection vs sizing attribution	API key
GET	/analysis/{id}/exposures	Factor exposure time series	API key
GET	/analysis/{id}/risk-decomposition	Attribution variance + confidence intervals	API key
POST	/analysis/{id}/insights	LLM narrative insights from cached metrics	API key
POST	/analysis/{id}/report	PDF report from cached analysis	API key
GET	/analysis/templates	List available report templates	—

Legacy Risk Endpoint

Method	Path	Description	Auth
POST	/risk	Run full pipeline end-to-end, return PDF report URL	API key

User Management Endpoints

Method	Path	Description	Auth
GET	/profile	Current user profile	API key
POST	/api-keys	Create a new API key	API key
GET	/api-keys	List your API keys	API key
DELETE	/api-keys/{id}	Revoke an API key	API key
POST	/create-user	Create a user (admin only)	API key
GET	/health	Health check	—

Example: Run Analysis

terminal

curl -X POST https://horizon-api.simudyne.com/analysis \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "portfolio_weights": [
      {"symbol": "AAPL", "weight": 0.15},
      {"symbol": "MSFT", "weight": 0.12},
      {"symbol": "GOOGL", "weight": 0.10},
      {"symbol": "AMZN", "weight": 0.08},
      {"symbol": "META", "weight": 0.07},
      {"symbol": "NVDA", "weight": 0.06},
      {"symbol": "TSLA", "weight": 0.05},
      {"symbol": "JPM", "weight": 0.05},
      {"symbol": "JNJ", "weight": 0.04},
      {"symbol": "V", "weight": 0.04},
      {"symbol": "PG", "weight": 0.04},
      {"symbol": "UNH", "weight": 0.04},
      {"symbol": "HD", "weight": 0.03},
      {"symbol": "MA", "weight": 0.03},
      {"symbol": "BAC", "weight": 0.03},
      {"symbol": "XOM", "weight": 0.02},
      {"symbol": "PFE", "weight": 0.02},
      {"symbol": "COST", "weight": 0.01},
      {"symbol": "ABBV", "weight": 0.01},
      {"symbol": "CRM", "weight": 0.01}
    ]
  }'

Example Response

response.json

{
  "session_id": "a1b2c3d4e5f67890",
  "cumulative_return": 0.0842,
  "annualized_return": 0.1125,
  "annualized_vol": 0.1683,
  "sharpe_ratio": 0.669,
  "max_drawdown": -0.0934,
  "market_return": 0.0756,
  "market_sharpe": 0.612,
  "idio_return": 0.0086,
  "idio_sharpe": 0.241,
  "start_date": "2024-03-15",
  "end_date": "2026-03-14",
  "trading_days": 504,
  "top_factors": [
    {"factor": "market", "cumulative_pnl": 0.0756, "sharpe_ratio": 0.612},
    {"factor": "Information Technology", "cumulative_pnl": 0.0312, "sharpe_ratio": 0.445}
  ],
  "bottom_factors": [
    {"factor": "vol_score", "cumulative_pnl": -0.0089, "sharpe_ratio": -0.312}
  ]
}

Use the returned session_id to call any drilldown endpoint without re-running the pipeline. Sessions expire after 2 hours.