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.
Charts are not rendered inside the chat client. Every tool result that produces a run includes a clickable result_url back to the Folio Lab report page, which is the only place the interactive frontier, weight breakdown, drawdown chart, and PDF report live.
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 22 tools, split into read-only and write groups. Each tool carries a machine-readable annotation (readOnlyHint or destructiveHint) so the assistant knows which operations are safe to execute without an extra confirmation step.
Read-only tools (17)
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. |
| 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. |
| 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 (5)
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. Counts against your monthly quota. |
| submit_us_optimization | Submits a new optimization run for US (NYSE/NASDAQ) stocks. 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 | Generates and emails the PDF report for a completed run. |
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) | Planned. ChatGPT's MCP support is in beta on Business/Enterprise/Edu plans; we are working through the connector spec on our side. | — |
| 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.
- No chart rendering in chat. The assistant receives structured data only. To see the efficient frontier, weights chart, drawdown curve, or download the PDF, open the
result_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.