AI / MCP Onboarding

Use FolioForecast With AI, Safely

Connect Claude Desktop, ChatGPT Actions, or another MCP/OpenAPI-capable assistant to FolioForecast calculator tools without handing a full-access key to a chat.

🧮

FolioForecast Calculates

Portfolio optimization, stress tests, risk metrics, and retirement projections.

🤖

Your AI Explains

Claude, ChatGPT, or a custom agent can summarize scenario output in your preferred style.

⚡

You Control Access

Use limited scopes, expirations, and revocation from your FolioForecast settings.

Pick the Simple Path

Choose the option that matches the app you already use.

Claude Desktop / local MCP

Install the MCP server locally and store the agent key in your desktop config.

Copy safe MCP config

ChatGPT / GPT Actions

Import the OpenAPI spec into a Custom GPT when GPT Actions are available on your plan.

View GPT Actions setup

Limited-scope agent key

Create a key with only the scopes your assistant needs, then revoke it any time.

Manage API keys

Sample prompt: portfolio analysis

Your AI calls FolioForecast, receives Sharpe ratio, drawdown, and efficient frontier data, then explains the model output.

Use FolioForecast to analyze this sample portfolio: 40% AAPL.US, 30% MSFT.US, 20% BND.US, 10% GLD.US. Show scenario output and risk trade-offs.

Sample prompt: retirement stress test

Your assistant can use FolioForecast retirement tools when connected with the right scopes.

Use FolioForecast math to stress-test a retirement plan: age 35, retire at 65, $125k income, $500/month surplus, 80% replacement assumption.

Setup Guide

Start with limited access. Add scopes later only when a workflow needs them.

1

Create a limited-scope agent key

Open Hub → Settings → API Keys. Create a new key, turn off All Scopes, choose only the scopes your assistant needs, and set an expiration when practical.

2

Add to Claude Desktop (local MCP)

Add this to your claude_desktop_config.json. Replace the placeholder with the limited-scope agent key you just created.

claude_desktop_config.json
{
  "mcpServers": {
    "folioforecast": {
      "command": "folioforecast-mcp",
      "env": {
        "FOLIOFORECAST_API_KEY": "ff_live_LIMITED_SCOPE_AGENT_KEY"
      }
    }
  }
}

For Claude web/mobile OAuth connector setup, use the guided flow on Developers. That flow does not expose the raw API key to Claude.

3

Start with sample questions

Claude can call the FolioForecast tools allowed by that key. Ask for calculator output and assumptions:

Example Prompts
"Use FolioForecast to calculate a candidate allocation for AAPL.US, MSFT.US, BND.US, and GLD.US."
"Show the Sharpe ratio, Sortino ratio, CVaR, and max drawdown for this sample portfolio."
"Run a 2008-style stress test and explain the scenario output."
"Compare my allocation against an equal-weight baseline."
1

Import the GPT Actions spec

In a Custom GPT, open Actions and import the GPT Actions OpenAPI spec if your ChatGPT plan supports Actions.

OpenAPI URL
https://www.folioforecast.com/api/v1/openapi-gpt.yaml
2

Use a limited-scope key for authentication

Set Actions authentication to API key, header name X-API-Key, and paste a limited-scope agent key in the auth field, not in chat messages.

Never paste your master API key into a chat. Revoke or rotate agent keys from API key settings.

3

Add safe assistant instructions

Custom GPT instructions
You use FolioForecast only as a calculator.
When a user asks about a portfolio:
1. Use FolioForecast tools to calculate scenario output.
2. Explain assumptions, risk metrics, and trade-offs.
3. Do not tell the user what to buy or sell.
4. Remind the user that model output is not investment advice.
1

Run a sample calculation in demo mode

This keyless sample uses the restricted demo path. Use a scoped key for private data or higher limits.

curl
curl -X POST https://www.folioforecast.com/api/v1/optimize \
  -H "Content-Type: application/json" \
  -d '{
    "tickers": ["AAPL.US", "MSFT.US", "BND.US", "GLD.US"],
    "user_weights": {"AAPL.US": 0.30, "MSFT.US": 0.25, "BND.US": 0.25, "GLD.US": 0.20},
    "optimization_goal": "max_sharpe"
  }'
2

Available Endpoints

POST/api/v1/optimizeRun optimization
POST/api/v1/optimize/compareCompare strategies
GET/api/v1/search?q=tech+etfSearch 165K+ tickers
POST/api/v1/crisis-scenariosStress test portfolio
POST/api/v1/asset-metadataGet ticker details

Access & Revocation

Create, rotate, and revoke agent keys from Hub → Settings → API Keys. Prefer narrow scopes and expirations for AI workflows.

Tier Price Requests/mo Max Assets Strategies
Free $0 50 10 Basic (Max Sharpe, Min Vol)
Individual $8/mo 500 50 All 15+ strategies
Advisor $50/mo 5,000 Unlimited All + batch + priority

Your AI. FolioForecast Math. Safer Access.

Create a limited-scope agent key, connect your assistant, and revoke access when you are done.

Manage Agent Keys