> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formo.so/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP overview
> Connect AI agents, coding tools, and third-party apps to Formo with MCP.
## Overview
The Formo MCP Server lets AI assistants, code editors, and custom integrations query your analytics data in natural language, using [MCP](https://modelcontextprotocol.io/), an open standard for connecting AI assistants to external data. For example:
* "How many daily active users did we have last week?"
* "What are the top acquisition sources this month?"
* "Show me user retention by cohort"
MCP requires a **Scale or Enterprise** plan. [Upgrade your workspace](https://app.formo.so) to get access.
## Getting started
**Supported clients:** OAuth-capable MCP clients such as ChatGPT, Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, or any client that supports HTTP or stdio MCP transports.
Formo supports two authentication methods for MCP:
* **OAuth (Recommended)** for clients that manage user sign-in. Users sign in to Formo, select a project on the consent page, and choose which permissions to approve.
* **Workspace API Keys** for clients that let you configure an `Authorization` header manually.
Connect OAuth-capable MCP clients to Formo.
Configure local clients, editors, and tools with an API Key.
## Example questions
**Product analytics**
* "What are my KPIs for the last 7 days?"
* "Show me daily active users for the past month"
* "Which lifecycle stage are most of my users in?"
* "What's the conversion rate from page view to wallet connection?"
**Marketing attribution**
* "What are my top traffic sources?"
* "Show me conversion by UTM source"
* "Which countries are my users coming from?"
**Wallet intelligence**
* "Look up the profile for this wallet address, including its net worth"
* "What are my top wallets and chains?"
## Available tools
### Query API
SQL, exploration, and pre-built analytics endpoints.
Permission: `query:read`.
| Tool | Description |
| :- | :- |
| `execute_query` | Run SQL queries against your analytics data |
| `text_to_sql` | Convert natural language to SQL |
| `list_endpoints` | List available API endpoints |
| `list_datasources` | List available data sources |
| `call_endpoint` | Low-level compatibility dispatcher for published endpoints |
| `kpis` | Get key performance indicators |
| `distinct_values` | Get unique values for filtering |
| `top_events` | View most common events |
| `event_timeseries` | Event counts over time |
| `lifecycle` | Lifecycle stage breakdown (new, returning, power, at risk, churned, resurrected) |
| `retention` | User retention by cohort |
| `frequency` | How often users return |
| `project_users` | Row-level user list, filterable by lifecycle stage, token holdings, and more |
| `top_pages` | Analyze page performance |
| `top_sources` | Attribution and traffic sources |
| `top_locations` | Geographic distribution |
| `top_wallets` | Most active wallets |
| `top_chains` | Activity by blockchain |
| `revenue_overview` | Revenue analytics |
| `revenue_timeseries` | Revenue over time for a wallet address (`address` is required) |
| `revenue_by_metric` | Revenue broken down by a dimension |
| `volume_by_metric` | Transaction volume broken down by a dimension |
| `cohort_analysis` | Cohort-based behavioral analysis |
| `funnel` | Multi-step conversion funnels |
| `flow` | User journey and path analysis |
### Profiles API
Wallet enrichment and profile writes.
| Tool | Description | Permission |
| :- | :- | :- |
| `search_profile` | Look up enrichment for a single wallet address (net worth, tokens, labels) | `profiles:read` |
| `update_profile_properties` | Set or unset profile properties on a wallet (address or ENS name); a `null` value deletes the property | `profiles:write` |
| `upsert_profile_labels` | Add or update labels on a wallet | `profiles:write` |
| `delete_profile_label` | Delete a label from a wallet | `profiles:write` |
| `batch_update_profile_properties` | Set or unset profile properties on up to 100 wallets in one call; `null` values delete | `profiles:write` |
| `batch_upsert_profile_labels` | Add, update, or delete labels on up to 100 wallets in one call (`_is_deleted: 1` rows tombstone) | `profiles:write` |
| `import_wallets` | Import wallets as identified users (Scale and Enterprise plans; imported wallets count toward monthly active user billing) | `profiles:write` |
### Alerts
| Tool | Description | Permission |
| :- | :- | :- |
| `list_alerts`, `get_alert` | Read alerts | `alerts:read` |
| `create_alert`, `update_alert`, `toggle_alert`, `delete_alert` | Manage alerts | `alerts:write` |
### Charts
| Tool | Description | Permission |
| :- | :- | :- |
| `list_boards`, `get_board`, `list_charts`, `get_chart` | Read boards and charts | `boards:read` |
| `execute_saved_chart` | Run a saved chart's query with a chosen date range | `boards:read` |
| `create_board`, `update_board`, `delete_board` | Manage boards | `boards:write` |
| `create_chart`, `update_chart`, `delete_chart`, `duplicate_chart`, `move_chart`, `reorder_charts` | Manage charts | `boards:write` |
| `preview_chart` | Run a chart's SQL without saving | `query:read` |
### Contracts
| Tool | Description | Permission |
| :- | :- | :- |
| `list_contracts`, `get_contract` | Read tracked contracts | `contracts:read` |
| `create_contract`, `update_contract`, `delete_contract` | Manage tracked contracts (pipeline inclusion is set via `update_contract`) | `contracts:write` |
### Segments
| Tool | Description | Permission |
| :- | :- | :- |
| `list_segments` | Read segments | `segments:read` |
| `create_segment`, `delete_segment` | Manage segments | `segments:write` |
The `delete_*` tools permanently remove data. They will not run unless the
call passes `"confirm": true`, so an assistant has to ask you first rather
than delete on its own. Grant write permissions only to clients you trust.
### Docs
| Tool | Description |
| :- | :- |
| `search_formo_docs` | Search the Formo documentation |
| `query_docs_filesystem_formo_docs` | Query the Formo docs filesystem |
## Troubleshooting
* **`403 MCP access requires a Scale or Enterprise plan`:** MCP is available only on Scale and Enterprise plans.
* **Tools not appearing:** Check that the URL ends with a trailing slash: `https://api.formo.so/v0/mcp/`. Restart or refresh your AI assistant after configuration changes.
* **OAuth issues:** See [MCP OAuth](/mcp/oauth) for OAuth setup, metadata, and troubleshooting.
* **API key issues:** See [MCP API Key](/mcp/api-key) for API key setup and troubleshooting.
### Security
* **Project-scoped:** each connection is limited to one project, either selected on the OAuth consent page or attached to the API key.
* **Permission-scoped:** every tool call requires the matching permission (e.g. `query:read` to read analytics, `alerts:write` to change alerts); deletes additionally require `"confirm": true`.
* **Owner/admin only:** only a workspace owner or admin can create a connection.
* **Nothing retained:** the MCP server itself stores no data.
* **Manage anytime:** review, change, or revoke access under **Settings** → **Connected apps**. Disconnects apply immediately; permission changes apply on reconnect. Sessions expire after 1 hour of inactivity.
## FAQ
Any OAuth-capable or HTTP/stdio MCP client. See [Getting started](#getting-started) for the supported client list and setup instructions.
Anything in the [Available tools](#available-tools) table: KPIs, traffic sources, pages, events, geography, revenue, lifecycle, retention, cohorts, funnels, and wallet enrichment.
Yes, access is scoped to one project and the permissions you grant. See [Security](#security) for details.
Yes. OAuth is additive. Existing Workspace API Key configurations continue to work with `Authorization: Bearer YOUR_API_KEY`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.