Folio Lab/Documentation

Connect Folio Lab to Claude

Add Folio Lab as a custom MCP connector inside Claude. Once connected, you can run optimizations (including rolling walk-forward backtests), fetch results, search Indian stocks, mutual funds, and US (NYSE/NASDAQ) equities, and look up documentation by chatting with Claude. The setup takes about two minutes.

Before you start

Subscription requirements

  • A Folio Lab Pro or Enterprise subscription. Free tier accounts cannot connect AI assistants - the MCP server returns 401 on every call.
  • A Claude account that allows custom connectors. Free Claude accounts can add one custom connector; Pro, Max, Team, and Enterprise plans have no limit.
  • You must be signed in to foliolab.ai in the same browser session before you start the connector flow. Either Google sign-in or email/password works.

The Folio Lab MCP URL

The only piece of configuration you need to paste into Claude is the MCP server URL:

https://api.foliolab.ai/mcp

Both https://api.foliolab.ai/mcp and https://api.foliolab.ai/mcp/ work - our gateway rewrites bare requests internally. Everything after that point (OAuth discovery, token exchange, scope consent) is handled automatically by Claude and our server.

Step-by-step

1. Open Claude's Connectors settings

In the Claude web app or desktop client, open Settings → Connectors. Scroll past the official Connectors Directory entries to the bottom of the page.

2. Click “Add custom connector”

Claude will ask for a name and a remote MCP server URL.

  • Name: Folio Lab (or whatever you want it to appear as in the connector list).
  • Remote MCP server URL: https://api.foliolab.ai/mcp

Confirm. Claude will ping our server, discover the OAuth metadata, and pop up an authorization window.

3. Sign in to Folio Lab (if you aren't already)

The authorization window is hosted on foliolab.ai. If you don't have an active session, you'll see the normal sign-in screen.

Both authentication methods work for the connector flow:

  • Google sign-in - one click if you already have a Folio Lab account linked to that Google identity.
  • Email and password - works exactly the same way. Your email must be verified.

4. Review the consent screen

You'll see a list of scopes Claude is requesting (read and write on runs, read on catalogue and documentation, etc.) along with a summary of which Folio Lab tools the assistant will be able to call.

Click Approve. The window closes and Claude shows the connector as connected.

5. Try a first prompt

Start a new Claude conversation and try one of these. Claude should pick the right tool automatically and surface the result with a clickable result_url back to your Folio Lab report page.

Read-only probe

“What are my last three Folio Lab runs and their Sharpe ratios?”

Exercises list_recent_runs + compare_runs.

First optimization

“Build a max-Sharpe portfolio of TCS, INFY, HDFCBANK, RELIANCE and ICICIBANK using HRP. Use Nifty 50 as the benchmark.”

Exercises submit_optimization then get_job_status / get_job_result.

US optimization (Pro)

“Build a min-volatility portfolio of Apple, Microsoft, Nvidia and Berkshire Hathaway, benchmarked to the S&P 500.”

Exercises search_us_stocks then submit_us_optimization.

Mutual funds

“Optimize a portfolio of Parag Parikh Flexi Cap, HDFC Flexi Cap and Quant Small Cap with HRP and MinVol.”

Exercises search_mutual_funds then submit_optimization with scheme codes. Equity funds only; a single run cannot mix stocks and funds.

Optimization with a rolling backtest

“Optimize TCS, INFY, HDFCBANK, RELIANCE and ICICIBANK with HRP and Min Volatility, and backtest it with quarterly rebalancing over a rolling 3-year window.”

Exercises submit_optimization with a rolling_backtestconfig. Claude summarizes the walk-forward numbers in-chat; the full suite (weight timeline, per-period turnover, out-of-sample metrics) lives on the run's results page. See the rolling backtest guide for the configuration options.

In-chat chart and report downloads

“Chart the cumulative returns of my last run against the benchmark, and get me the Excel and PDF.”

Exercises get_chart_data (Claude assembles the chart from a compact data packet) and get_report_files (1-hour signed download links; the PDF is generated on demand if missing).

Documentation lookup

“What is the Sharpe Stability Ratio and when should I prefer it over plain Sharpe?”

Exercises search_docs + get_doc.

Troubleshooting

“Connection failed” / “Could not reach server”

Most often a copy-paste mistake on the MCP URL. Confirm you pasted https://api.foliolab.ai/mcp exactly. The server is HTTPS-only and rejects HTTP.

Authorization window opens, then immediately closes

A pop-up blocker is stripping the OAuth window. Disable blocking for foliolab.ai and retry. On Claude desktop, this shows up as the window flashing and then vanishing without a consent screen.

Consent screen says “Pro subscription required”

The account you signed in with is on the Free tier. Upgrade from the pricing page and retry the connector. Connector entitlement is checked at every tool call, so the upgrade takes effect immediately.

Tool calls return 401 after I changed my password

Changing your account password does not automatically revoke outstanding MCP tokens, but other operations can. Reconnect the connector in Claude - the OAuth flow will re-issue fresh tokens.

“Quota exceeded” on submit_optimization

MCP submissions count against your normal monthly run cap (50 on Pro). The counter is shared with website submissions and resets on your billing-cycle date. Enterprise plans have no cap.

Revoking the connector

You can disconnect Folio Lab from Claude in two ways, depending on whose side you want to control:

  • From Claude:Settings → Connectors → Folio Lab → Remove. This stops Claude from making any further calls but does not revoke the token on our side.
  • From Folio Lab: Open the account settings page, scroll to the Connectors section, and revoke the active grant. This invalidates the token server-side immediately - subsequent calls from Claude will fail with 401, and Claude will prompt you to reconnect if you want to use the connector again.

Revocation does not delete the runs or data already created through the connector. Those remain in your account history.

Working effectively with the assistant

  • Resolve tickers first.If you give Claude a company name (“Bharat Electronics”), it will call search_stocks to find the canonical NSE/BSE symbol before submitting - or search_us_stocksfor a US name (“Apple”). Don't hand-type tickers if you're unsure of the exact symbol.
  • Ask for charts, but click the result_url for the full picture. Claude can sketch quick comparison charts in-chat from compact data packets (get_chart_data) and hand you Excel/PDF download links (get_report_files). The interactive frontier, per-asset drill-down, full-resolution drawdown curve, and the rolling-backtest suite still live on the Folio Lab report page.
  • Verify numbers Claude quotes in its narrative. The assistant can paraphrase tool outputs incorrectly, e.g. swapping a Sharpe for a Sortino. Open the report page and cross-check before acting on anything.
  • Use templates for repeat workflows. If you run the same optimization shape repeatedly, save it as a template from the website. Claude can then load it via list_templates instead of re-typing the full configuration each time.

Reference