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.
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 (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?”
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
Authorizationheader manually.
The MCP server URL is always
https://api.formo.so/v0/mcp/. Keep the trailing slash and do not use the API root URL.OAuth setup
Connect OAuth-capable MCP clients to Formo.
API key setup
Configure local clients, editors, and CLI bridges with a Workspace API Key.
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?”
- “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?”
- “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 |
| 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) |
| Tool | Description |
|---|---|
search_formo_docs | Search the Formo documentation |
query_docs_filesystem_formo_docs | Query the Formo docs filesystem |
The exact set of tools depends on your project’s configured endpoints. Use
list_endpoints to discover what’s available for your project.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
Which AI tools support the Formo MCP Server?
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.
What analytics data can I query through the MCP Server?
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).
Is my analytics data secure when using the MCP Server?
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.
Can I still use an API key?
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.Troubleshooting
403 MCP access requires a Scale or Enterprise plan: MCP is available only on Scale and Enterprise plans. Upgrade your workspace 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 for OAuth setup, metadata, and troubleshooting.
API key issues: See MCP API Key for API key setup and troubleshooting.