Folio Lab/Documentation

Connect Folio Lab to Claude

Add Folio Lab as a custom MCP connector inside Claude. Once connected, you can run optimizations, 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 Enterprisesubscription. 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.

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_stocksto 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.
  • Always click the result_url. Claude does not render charts. The interactive frontier, per- asset weight chart, drawdown curve, and PDF download all 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