AI Assistants (MCP)
Connect Folio Lab to any MCP-compatible AI assistant. 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.
Folio Lab implements the MCP specification rather than any single vendor's dialect, so the same server URL works everywhere. Setup walkthroughs: Claude and ChatGPT.
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 conversation in any of those clients 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 37 tools, split into read-only and write groups. Every run capability the REST API exposes is reachable through MCP: both surfaces call the same service functions, so payloads cannot diverge between them, and a test fails if a service capability is ever added without a matching tool. 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 (27)
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_monte_carlo_result | Status and results of a Monte Carlo simulation, including ready-made interpretation sentences and the explicit modeling assumptions behind every probability. |
| list_monte_carlo_runs | List all Monte Carlo simulations attached to one optimization run. |
| get_monte_carlo_chart_data | Compact chart packets for a completed simulation (wealth fan, terminal distribution, drawdown state, goal probability over time and more) as pre-shaped arrays the assistant renders client-side. |
| list_all_monte_carlo_runs | List simulations across every parent run, cursor paginated. |
| get_backtest_result | Status and results of a persisted walk-forward backtest child run, with its metric suite and Sharpe inference. |
| list_backtest_runs | List the backtests attached to one optimization run. |
| list_all_backtest_runs | List backtests across every parent run, cursor paginated. |
| list_active_jobs | Everything currently queued or running on your account. |
| list_run_tags | Read the tags applied to a run. |
| get_doc | Fetch the full content of a documentation page by path. |
Write tools (10)
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. |
| submit_monte_carlo | Submits a forward Monte Carlo wealth simulation on a succeeded Indian run (SIP/SWP cash flows, goals, tax, crisis scenarios, walk-forward re-optimization and the paired frozen-weight baseline). Counts against the separate Monte Carlo quota: Pro 20 runs/month and up to 50,000 paths, Enterprise unlimited runs and up to 100,000 paths. |
| 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. |
| submit_backtest | Queues a persisted walk-forward backtest against a succeeded parent run. Counts against the separate backtest quota. |
| tag_run | Applies a tag to a run. |
| untag_run | Removes a tag from a run. |
| 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). |
Discoverability: every legal value is in the schema
Every constrained parameter advertises its full vocabulary in the tool schema, derived from the enum that defines it rather than retyped: all 31 optimization methods, all 14 Indian and 3 US benchmarks, the return processes, stress scenarios, goal bases, drift modes, rebalance cadences, risk-free tenors, chart names and search operators. A client that never reads an MCP resource can still enumerate every legal value, and a single request may carry the entire method catalogue.
Common aliases such as “hierarchical risk parity” and “mean variance” normalize server-side, and an unrecognized method returns the offending names alongside the full valid list rather than a bare validation error.
Three resources back this up: config://methods, config://benchmarks and config://us_benchmarks, each generated from the enum that defines it so a new member cannot go missing. They carry a description per entry.
Deliberately outside the MCP surface: authentication, billing, OAuth client management, account settings, the in-app chat endpoints, and the frontend's own UI state. These are session, security or presentation concerns rather than analysis capability.
Charts are data, never images
Chart data is returned as data-only JSON packets under a 25 KB budget and the client renders them. Nothing is rendered server-side as an image, so an assistant can restyle, re-scale or combine a chart without a round trip, and no rendering assumption is baked into the payload.
get_monte_carlo_chart_data serves eleven packets: wealth_fan, goal_probability, terminal_quantiles, path_metric, drawdown_state, scenarios, metric_suite, plus the walk-forward set weight_paths, goal_ladder, annualized_return and paired_comparison. The last two take a view argument to select between series that do not share an axis.
The metric_suite packet plots the stored P5, P25, P50, P75 and P95 across paths plus the cross-path mean, and carries defined-path and observation counts. A missing risk-free benchmark, and the mathematically inapplicable simulated-path Deflated Sharpe and Sharpe Stability cases, fail with the engine's explicit reason rather than returning a zero benchmark or a misleading statistic.
Every paired_comparison view states in its footnote that the two arms ran identical paths and that a ratio above 1 is not evidence that re-optimizing outperforms. Monte Carlo results must always be presented with their assumptions block: probabilities are conditional on the model and the frozen history, and are never forecasts. See rolling-origin validation.
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. | Walkthrough → |
| 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.
Not investment advice. Past performance is not indicative of future results.