> ## 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 custom workflows to Formo with MCP.

## Overview

The Formo MCP Server enables AI tools, OAuth-capable clients, editor integrations, and custom workflows to query your analytics data directly. Ask questions about your users, events, and metrics in natural language.

The [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open standard that allows AI assistants to connect to external data sources and tools. With Formo's MCP server, you can ask:

* "How many daily active users did we have last week?"
* "What are the top acquisition sources this month?"
* "Show me user retention by cohort"
* "Which pages have the highest bounce rate?"

<Warning>
  The Formo MCP server requires a **Scale or Enterprise** plan. This applies to both OAuth and Workspace API key connections. Free and Growth workspaces cannot connect to MCP and will receive a `403` error (`MCP access requires a Scale or Enterprise plan`). [Upgrade your workspace](https://app.formo.so) to enable MCP access.
</Warning>

## Getting started

**Supported clients:** OAuth-capable MCP clients, Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, Codex, and any client that supports HTTP or stdio MCP transports.

Formo supports two authentication methods for MCP:

* **OAuth** for clients that manage user sign-in. Users sign in to Formo, select a project on the consent page, and approve read-only MCP access.
* **Workspace API keys** for clients that let you configure an `Authorization` header manually.

<Note>
  The MCP server URL is always `https://api.formo.so/v0/mcp/`. Keep the trailing slash and do not use the API root URL.
</Note>

<CardGroup cols={2}>
  <Card title="OAuth setup" icon="key" href="/mcp/oauth">
    Connect OAuth-capable MCP clients to Formo.
  </Card>

  <Card title="API key setup" icon="brackets-curly" href="/mcp/api-key">
    Configure local clients, editors, and CLI bridges with a Workspace API Key.
  </Card>
</CardGroup>

## Example queries

Once connected, try these prompts with your AI assistant:

**Traffic & Events**

* "What are my KPIs for the last 7 days?"
* "What are my top traffic sources?"
* "Which pages have the highest engagement?"
* "Show me traffic by country"
* "What are the most common events?"

**Custom Queries**

* "How many users signed up this week?"
* "Show me daily active users for the past month"
* "What's the conversion rate from page view to wallet connection?"

**Web3 Analytics**

* "Look up the profile for this wallet address, including its net worth"
* "What are my top wallets and chains?"

## Available tools

The Formo MCP server exposes a curated set of tools, grouped below.

**Core**

| Tool               | Description                                                   |
| :----------------- | :------------------------------------------------------------ |
| `explore_data`     | Natural language data exploration with Formo-specific context |
| `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                                   |

**Analytics endpoints**

| Tool                 | Description                                                                |
| :------------------- | :------------------------------------------------------------------------- |
| `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`          | New, returning, resurrected, and dormant users                             |
| `retention`          | User retention by cohort                                                   |
| `frequency`          | How often users return                                                     |
| `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                                                          |
| `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                                             |
| `search_profile`     | Look up enrichment for a single wallet address (net worth, tokens, labels) |

**Docs**

| Tool                               | Description                     |
| :--------------------------------- | :------------------------------ |
| `search_formo_docs`                | Search the Formo documentation  |
| `query_docs_filesystem_formo_docs` | Query the Formo docs filesystem |

<Note>
  The exact set of tools depends on your project's configured endpoints. Use `list_endpoints` to discover what's available for your project.
</Note>

`lifecycle`, `retention`, and `frequency` are first-class MCP tools. For user-level lists or cohort exports, use `text_to_sql` + `execute_query` to query the users datasource directly.

## FAQ

<AccordionGroup>
  <Accordion title="Which AI tools support the Formo MCP Server?">
    The Formo MCP Server works with OAuth-capable MCP clients, Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, Codex, and any AI client that supports HTTP or stdio MCP transports. See the OAuth and API key setup pages above for configuration instructions.
  </Accordion>

  <Accordion title="What analytics data can I query through the MCP Server?">
    You can query KPIs, traffic sources, top pages, top events, geographic distribution, revenue, lifecycle, retention, frequency, cohorts, funnels, and wallet enrichment. Most of these are available as first-class tools (see [Available tools](#available-tools)).
  </Accordion>

  <Accordion title="Is my analytics data secure when using the MCP Server?">
    Yes. The MCP Server provides read-only access scoped to one Formo project. OAuth users select the project during consent, and API keys are project-specific. No data is stored by the MCP server itself.
  </Accordion>

  <Accordion title="Can I still use an API key?">
    Yes. OAuth is additive. Existing Workspace API Key configurations continue to work with `Authorization: Bearer YOUR_API_KEY`.
  </Accordion>
</AccordionGroup>

## Troubleshooting

**`403 MCP access requires a Scale or Enterprise plan`:** MCP is available only on Scale and Enterprise plans. [Upgrade your workspace](https://app.formo.so) to connect MCP.

**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

The Formo MCP server provides read-only access to analytics data. OAuth access is scoped to the project selected on the Formo consent page. API key access is scoped to the project attached to the key. MCP sessions expire after 1 hour of inactivity.