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. A re-optimize schedule can also be set: it must equal the rebalance schedule or be less frequent, and between refits the book trades back to the last fitted target. 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. ChatGPT needs a Business, Enterprise, or Edu plan with Developer Mode enabled.

SidePlan that worksNotes
Folio LabPro (Monthly or Yearly), EnterpriseA Free account cannot complete the connection: the consent step refuses it and no access is issued.
ClaudeFree (1 custom connector), Pro, Max, Team, EnterpriseCustom connectors are currently in beta on Claude.
ChatGPTBusiness, Enterprise, EduDeveloper Mode must be on. See the ChatGPT walkthrough.

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 43 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 (32)

These do not change any state. Safe to call freely.

ToolPurpose
search_stocksResolve a company name or partial symbol to NSE/BSE tickers.
resolve_tickerDisambiguate a single name to a canonical ticker.
search_mutual_fundsFind Indian mutual funds by name, category, or AMC.
search_us_stocksResolve a company name or partial ticker to US-listed equities (NYSE/NASDAQ).
import_holdingsRead a Zerodha or Groww holdings export into two starting portfolios, stocks and mutual funds, with each removed or unmatched holding named. See Optimize from Holdings.
list_recent_runsPaginate through your previous optimization runs.
get_job_statusPoll the status of a submitted run.
get_job_resultFetch the weights, metrics, and per-asset stats of a completed run, including a compact headline summary (best method, key metrics, top holdings).
get_chart_dataCompact, downsampled chart data packets (weights, metric comparison, cumulative returns) the assistant renders as an in-chat chart.
get_job_configRead back the original submission inputs of a run.
get_run_artifactsList downloadable artifacts attached to a run (Excel, PDF, JSON).
get_analytics_summaryTop-line dashboard stats across all your runs.
compare_runsSide-by-side comparison of metrics across multiple runs.
search_runs_by_metricFind your runs that satisfy a metric threshold.
explain_metricShort canonical explanation of any Folio Lab metric, with a link to its docs page and related metrics.
preview_constraintsCheck constraints against a universe before a run is spent. Answers which number to move and by how much, not just whether the mandate is feasible. Call it before submitting whenever the constraints carry a group rule.
list_classification_mapsList the sector lists saved on your account, with the id a group constraint uses to name one.
get_backtest_chart_dataThe walk-forward equity curve of one standalone backtest, as a compact downsampled packet the assistant renders in chat.
get_report_statusWhere a run’s PDF report is: absent, queued, rendering, ready or failed. Poll this rather than re-requesting the report, because it can tell a busy queue from a render that died.
list_templatesList your saved optimization templates.
list_docsList documentation pages in a given section.
search_docsFull-text search across the Folio Lab documentation.
get_monte_carlo_resultStatus and results of a Monte Carlo simulation, including ready-made interpretation sentences and the explicit modeling assumptions behind every probability.
list_monte_carlo_runsList all Monte Carlo simulations attached to one optimization run.
get_monte_carlo_chart_dataCompact 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_runsList simulations across every parent run, cursor paginated.
get_backtest_resultStatus and results of a persisted walk-forward backtest child run, with its metric suite and Sharpe inference.
list_backtest_runsList the backtests attached to one optimization run.
list_all_backtest_runsList backtests across every parent run, cursor paginated.
list_active_jobsEverything currently queued or running on your account.
list_run_tagsList every tag you have applied to runs, with a count for each tag.
get_docFetch the full content of a documentation page by path.

Write tools (11)

These change state on your account. The assistant should ask before calling them; Claude prompts you to confirm each destructive call by default. The in-app chat on Folio Lab asks you before it deletes or cancels a run, and acts only after your next message confirms it.

ToolWhat it changes
submit_optimizationSubmits 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 and a re-optimize schedule, a start and end date for the price history, and the starting weights from an imported holdings file. On Enterprise it also takes portfolio constraints and the Fund Manager Mode switch. Counts against your monthly quota. A request that cannot run, for example a stock with fewer than 150 daily prices or a symbol the exchange does not list, is refused with the reason before it is queued and uses no quota. On your request, the assistant can drop a short-history stock and run the rest.
submit_us_optimizationSubmits a new optimization run for US (NYSE/NASDAQ) stocks, with the same optional rolling backtest configuration and history window, and constraints on Enterprise. Requires Pro or Enterprise; counts against your monthly quota.
submit_monte_carloSubmits a forward Monte Carlo wealth simulation on a succeeded Indian run (SIP/SWP cash flows, goals, tax, crisis scenarios, walk-forward re-optimization, the paired frozen-weight baseline, and an opt-in buy-and-hold arm for a three-policy comparison on the same simulated paths, which is not evidence that one policy performs better). 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_jobCancels a queued or in-flight run.
rename_runSets a human-readable name on a run.
request_pdf_reportTriggers PDF generation for a completed run (idempotent); the file appears in the run's artifacts shortly after.
submit_backtestQueues a persisted walk-forward backtest against a succeeded parent run. It can set a re-optimize schedule, a flat transaction cost for the policy comparison, the never-rebalanced control arm, and the evaluation window. Counts against the separate backtest quota.
delete_runPermanently deletes one run and everything attached to it: its Monte Carlo simulations, backtests, artifacts, stored metrics and weights, tags, and its membership of any saved comparison. This cannot be undone, so the assistant confirms with you first.
tag_runApplies a tag to a run.
untag_runRemoves a tag from a run.
get_report_filesReturns 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.

Seven resources back this up: config://methods, config://method_requirements (the minimum assets each method needs, for example 4 for HERC2, stated before a model chooses one), config://benchmarks, config://us_benchmarks, config://constraint_capability (what each method does with each kind of constraint), config://constraint_presets (the SEBI presets a constraint block can name) and config://fund_manager_mode (the rules of Fund Manager Mode and what it does not add). Each is generated from the enum or table that defines it, so a new member cannot go missing, and each carries 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 Claude or ChatGPT, the assistant connects as a public OAuth client, with PKCE and no client secret, and goes 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/register and receives a per-instance client_id. No manual app-registration step on your part. Registration is limited to 30 requests a minute from each address.
  • Client ID Metadata Documents. A client such as ChatGPT can instead use an HTTPS URL as its client_id. The server fetches the document at that URL only from a public address it checked first, and accepts it when the document allows a public client.
  • 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 ends the grant's refresh tokens at once, so the assistant cannot renew its access. An access token it already holds stays valid until it expires, at most 15 minutes later; after that, its next tool call fails 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

ClientStatusSetup
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). A ChatGPT connector setup completed on production on 4 October 2026, as a public client with PKCE. Requires a ChatGPT Business, Enterprise, or Edu plan with Developer Mode enabled.Walkthrough →
Other MCP clientsShould work. The server implements the spec, not a Claude-specific or ChatGPT-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 the result_url returned 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.