AI Assistants (MCP)
Connect Folio Lab to AI assistants like Claude over the Model Context Protocol (MCP). The assistant gets read and write access to your account's portfolio optimization tools, scoped by OAuth, so you can run optimizations, fetch results, search Indian stocks, mutual funds, and US (NYSE/NASDAQ) equities, and look up metric or method documentation from inside a chat window.
What MCP is
The Model Context Protocol (MCP) is an open standard published by Anthropic in 2024 that lets AI assistants call tools on external servers using JSON-RPC over HTTP. It replaces the older assistant-specific plugin systems with a single transport that any compliant client - Claude, ChatGPT (in Developer Mode), Perplexity, and others - can use.
For Folio Lab specifically, MCP means a Claude conversation can run an optimization the same way you would from the optimizer page: the model sees a catalogue of tools (such as submit_optimization, list_recent_runs, get_job_result) with machine-readable schemas, picks the right tool for what you asked, calls our server with the right arguments, gets a structured response, and continues the conversation. Authentication, billing, run history, and quota all flow through your existing Folio Lab account.
The assistant can render quick charts in-chat: the get_chart_data tool returns compact, downsampled data packets (weights by method, metric comparisons, cumulative returns vs benchmark) that the assistant assembles into a chart on its side - no images cross the wire. These are snapshots, not the full experience: every run still includes a clickable result_url back to the Folio Lab report page, where the interactive frontier, weight breakdown, drawdown chart, and PDF report live.
Submissions can also include a rolling walk-forward backtest: ask the assistant for a rebalance schedule (annual, semi-annual, or quarterly) and an expanding or rolling training window, and the optimizer re-runs at every rebalance date exactly as it would for a website submission. The assistant reports the headline walk-forward numbers in-chat; the full suite (weight timeline, per-period turnover, out-of-sample metrics, Sharpe inference) renders on the run's results page.
Requirements
You need an active subscription on both sides
Folio Lab gates MCP access behind Pro or Enterprise. The Free tier cannot connect AI assistants. On the assistant side, custom MCP connectors (which is what Folio Lab is for now - we are not yet listed in Claude's public Connectors Directory) are available on Free with a one-connector cap, and unlimited on Pro, Max, Team, and Enterprise.
| Side | Plan that works | Notes |
|---|---|---|
| Folio Lab | Pro (Monthly or Yearly), Enterprise | Free tier returns 401 on every MCP tool call. |
| Claude | Free (1 custom connector), Pro, Max, Team, Enterprise | Custom connectors are currently in beta on Claude. |
See our pricing page for plan details, or your account settings to upgrade. For Claude plan details, see claude.com/pricing.
What the AI can do on your account
The Folio Lab MCP server exposes 24 tools, split into read-only and write groups. Each tool carries machine-readable annotations (readOnlyHint, destructiveHint, and openWorldHint for tools that reach external data sources) so the assistant knows which operations are safe to execute without an extra confirmation step.
Read-only tools (18)
These do not change any state. Safe to call freely.
| Tool | Purpose |
|---|---|
| search_stocks | Resolve a company name or partial symbol to NSE/BSE tickers. |
| resolve_ticker | Disambiguate a single name to a canonical ticker. |
| search_mutual_funds | Find Indian mutual funds by name, category, or AMC. |
| search_us_stocks | Resolve a company name or partial ticker to US-listed equities (NYSE/NASDAQ). |
| list_recent_runs | Paginate through your previous optimization runs. |
| get_job_status | Poll the status of a submitted run. |
| get_job_result | Fetch the weights, metrics, and per-asset stats of a completed run, including a compact headline summary (best method, key metrics, top holdings). |
| get_chart_data | Compact, downsampled chart data packets (weights, metric comparison, cumulative returns) the assistant renders as an in-chat chart. |
| get_job_config | Read back the original submission inputs of a run. |
| get_run_artifacts | List downloadable artifacts attached to a run (Excel, PDF, JSON). |
| get_analytics_summary | Top-line dashboard stats across all your runs. |
| compare_runs | Side-by-side comparison of metrics across multiple runs. |
| search_runs_by_metric | Find your runs that satisfy a metric threshold. |
| explain_metric | Short canonical explanation of any Folio Lab metric, with a link to its docs page and related metrics. |
| list_templates | List your saved optimization templates. |
| list_docs | List documentation pages in a given section. |
| search_docs | Full-text search across the Folio Lab documentation. |
| get_doc | Fetch the full content of a documentation page by path. |
Write tools (6)
These change state on your account. The assistant should ask before calling them; Claude prompts you to confirm each destructive call by default.
| Tool | What it changes |
|---|---|
| submit_optimization | Submits a new optimization run for Indian stocks or mutual funds (equity funds by AMFI scheme code; stocks and funds cannot mix in one run). Can optionally include a rolling walk-forward backtest with a rebalance schedule. Counts against your monthly quota. |
| submit_us_optimization | Submits a new optimization run for US (NYSE/NASDAQ) stocks, with the same optional rolling backtest configuration. Requires Pro or Enterprise; counts against your monthly quota. |
| cancel_job | Cancels a queued or in-flight run. |
| rename_run | Sets a human-readable name on a run. |
| request_pdf_report | Triggers PDF generation for a completed run (idempotent); the file appears in the run's artifacts shortly after. |
| get_report_files | Returns 1-hour download links for the Excel and PDF reports of a run, generating the PDF on demand if it is missing (which is why it sits in the write group). |
Security model
The MCP server is protected by OAuth 2.1 with PKCE. When you add Folio Lab to an AI assistant, the assistant is treated as a public OAuth client and walked through the same standards-based authorization code flow a browser SPA would use.
- Dynamic Client Registration (RFC 7591). The assistant registers itself at
POST /oauth/registerand receives a per-instanceclient_id. No manual app-registration step on your part. - PKCE (RFC 7636). The flow uses S256 code challenges, so even if the authorization code is intercepted in transit it cannot be exchanged for a token by another party.
- Scoped tokens. Access tokens are RS256-signed JWTs with explicit scopes (
runs:read,runs:write,catalog:read, etc.). Each tool checks the scopes it needs; calls without the right scope are rejected. - You see the consent screen. Folio Lab redirects the assistant to a consent page hosted on this domain. You sign in with your existing account (Google or email/password) and explicitly approve the scopes before any token is issued.
- Revocable at any time. From the Connectors section of your account settings you can list active grants and revoke them. Revocation takes effect immediately - the assistant's next tool call will fail with 401.
Privacy
When you use Folio Lab through an AI assistant, your prompts and the tool inputs and outputs are processed by the AI provider you authorised. We do not control how that provider stores, logs, or uses your conversations. Review the assistant's privacy policy before sending portfolio data through it.
On the Folio Lab side, MCP tool calls are subject to the same privacy policy as any other authenticated request. The Section 10 AI Assistants and MCP Connectors provisions in our Terms of Service also apply.
Supported clients
| Client | Status | Setup |
|---|---|---|
| Claude (web, desktop) | Available as a custom connector. Folio Lab's entry in the public Connectors Directory is under review. | Walkthrough → |
| ChatGPT (Developer Mode) | Beta. Our server implements ChatGPT's connector requirements (CIMD client identity, audience-bound tokens). Requires a ChatGPT Business, Enterprise, or Edu plan with Developer Mode enabled. | Add a custom connector with the same MCP URL from Settings; OAuth and consent work the same way as Claude. |
| Other MCP clients | Should work. The server implements the spec, not a Claude-specific dialect. | - |
Limitations
- Quota is shared. Runs submitted via MCP count against the same monthly cap as runs submitted from the website. A Pro account that has used all 50 runs cannot submit more through an AI assistant either.
- In-chat charts are snapshots. The assistant can draw quick charts from downsampled data packets (via
get_chart_data), but these are compact summaries. For the interactive efficient frontier, full-resolution drawdown curve, per-asset drill-down, the rolling-backtest suite, or the PDF, open theresult_urlreturned by the tool. - The assistant can hallucinate. Treat any narrative summary or recommendation the AI writes about your portfolio as a starting point, not as advice. Verify every number against the underlying run.
- Long inputs are truncated. Very large universes (more than ~200 tickers) may be hard for the assistant to track accurately mid-conversation. Submit those from the website instead.