Connect Usermaven to AI tools with MCP

This guide explains what MCP is, what you can do with Usermaven's MCP server, and how to connect Usermaven to AI tools like ChatGPT, Claude, Cursor, and Codex.

No technical background is needed. If you have never used MCP before, start with the first section.

1. What is Usermaven MCP?

MCP stands for Model Context Protocol. It is a standard way for AI tools to connect to apps and use their data.

Think of MCP as a "plug" that lets an AI assistant reach into Usermaven and ask questions about your analytics.

Usermaven provides a public MCP server. When you connect it to an AI tool, the AI can:

Read your website and product analytics.
Ask questions about your data.
In some cases, create things like funnels and dashboards for you.

You talk to the AI normally, and the AI talks to Usermaven in the background. You do not need to copy and paste numbers into the chat.

2. What can you do with Usermaven MCP?

Usermaven MCP gives the AI access to your analytics in two groups: read actions and write actions.

Read actions (analyze your data)

These actions only look at your data. They do not change anything.

Website analytics – traffic, sessions, page views, sources, channels, devices, and countries.
Product analytics – trends, comparisons, and breakdowns.
Attribution – see which channels and campaigns drove signups, paying customers, and revenue.
Funnels – see how users move through a series of steps and where they drop off.
Customer journeys – see the path users take before a key event like a purchase.
Conversion analysis – review conversion goals.
Segments – view your saved audience segments.
Dashboards and reports – list and review existing dashboards and trend reports.
Taxonomy – discover your workspace's custom events and fields so the AI can ask smarter questions.

Write actions (make changes in Usermaven)

These actions create or update something in Usermaven. They require your approval before they run.

Create a funnel from steps you define.
Create a conversion goal.
Create or update a segment.
Create a journey.
Create a retention report.
Create or update a trend report.
Create a dashboard or add a tile to an existing dashboard.
Create an attribution view.

Mutations are only carried out when you explicitly ask the AI to make a change, and they always need your approval first.

The full list of read and write tools is described in more detail in Section 12, Read vs. write actions.

3. Before you begin

Before you connect Usermaven MCP, make sure you have:

A Usermaven account with a workspace you can access.
The correct permissions in Usermaven. You need to be able to view the workspace and its settings to connect MCP. If you cannot open the MCP settings in Usermaven, ask your workspace admin.
An MCP-compatible AI client. MCP works with AI tools that support connecting to MCP servers, such as ChatGPT, Claude, Cursor, and Codex.
A Usermaven plan that includes MCP. Check your Usermaven plan or contact support if you are not sure MCP is included for your workspace.

4. Connect Usermaven MCP (main setup flow)

The connection uses a standard MCP server address plus an authorization step.

The MCP server address is:

https://mcp.usermaven.com/mcp

If your client supports it, you can also use progressive discovery:

https://mcp.usermaven.com/mcp?discovery=progressive

The setup generally works like this:

Open your AI client's settings and find where to add an MCP server.
Choose to add a remote or URL-based MCP server.
Paste the MCP server address above.
Save the server. The client will open Usermaven's authorization (login and consent) screen.
Sign in to Usermaven, choose which workspaces to connect, choose the permissions you want to allow, and approve.
Return to your AI client. The connection is now set up and ready to use.

In Usermaven, open Settings → AI & MCP → “Use Usermaven in AI tools” to see the MCP server address and your authorization link.

5. Connect Usermaven to ChatGPT

Open ChatGPT and go to the section where you can add a custom tool or MCP connection.
Choose to add a remote MCP server.
Paste the server address:
```
https://mcp.usermaven.com/mcp
```
Save, then follow Usermaven's sign-in and approval prompts.
After approving, ChatGPT can connect to Usermaven and answer questions about your analytics.

ChatGPT and Codex connect to MCP servers using OpenAI's official Model Context Protocol support. See the screenshot below.

6. Connect Usermaven to Claude

Open Claude and go to the MCP / connectors settings.
Add a new remote MCP server.
Paste the server address:
```
https://mcp.usermaven.com/mcp
```
Save, then complete Usermaven's sign-in and approval flow.
Once connected, you can ask Claude questions about your Usermaven data.

Claude connects to MCP servers through its connectors settings. The official Claude documentation for connecting tools via MCP is shown below.

7. Connect Usermaven to Cursor

Open Cursor and go to the MCP configuration.
Add a new remote MCP server.
Paste the server address:
```
https://mcp.usermaven.com/mcp
```
Save, then complete Usermaven's sign-in and approval flow.
When connected, Cursor can pull in Usermaven analytics to help with your work.

Cursor supports MCP servers through its configuration. The official Cursor documentation is shown below.

8. Connect Usermaven to Codex

Open Codex and go to the MCP settings.
Add a new remote MCP server.
Paste the server address:
```
https://mcp.usermaven.com/mcp
```
Save, then complete Usermaven's sign-in and approval flow.
Once connected, you can ask Codex questions about your Usermaven data.

9. Authentication and permissions

When you connect Usermaven MCP for the first time, you go through an authorization flow. This is the same idea as "Sign in with Google" or "Connect your account" in other apps.

Here is what happens:

You sign in to Usermaven.
You choose which workspaces the connection is allowed to use.
You choose which permissions (called scopes) to allow.
You approve the connection.

What the permissions mean

Each permission controls what the AI can do:

Read workspace data – See the workspaces you selected and switch between them. This is always required and cannot be turned off.
Read analytics – Query trends, funnels, segments, dashboards, conversion goals, and your event taxonomy.
Read attribution – Query attribution views and paid-ads attribution reporting.
Read journeys – Query journeys and retention reports.
Create and update analytics – Create or update segments, funnels, dashboards, trend reports, and conversion goals.
Create and update journeys – Create or update journeys.

Read permissions let the AI look at your data. Write permissions let the AI make changes. Write actions always require your approval before they run.

Workspace access

The connection only sees the workspaces you selected during authorization. Each workspace also has its own MCP policy that can be turned on or off, and its own setting for whether writes are allowed. A workspace admin controls these settings.

10. Working with multiple workspaces

Usermaven MCP supports multiple workspaces on a single connection. You pick which workspaces to connect during authorization, and you can switch between them without reconnecting.

Check which workspaces you can access

Ask the AI to list your available workspaces. It uses a tool called List Available Workspaces (internally, workspace_list_available). The result shows the workspaces the connection is allowed to use and marks which one is currently active.

Example prompt:

"List my available workspaces."

Switch to another workspace

To work with a different workspace, tell the AI which one to switch to. It uses a tool called Switch Workspace (internally, workspace_switch).

Example prompt:

"Switch to my Acme workspace."

When you switch:

The AI confirms the switch and tells you which workspace is now active.
All follow-up questions are answered using that workspace.

What if you cannot access a workspace?

If the connection was not authorized for a workspace, the switch is blocked. Only the workspaces you selected during authorization can be used. To add a workspace, reconnect Usermaven and include it during authorization.

Default workspace

The workspace you selected when you first authorized the connection is the default. If you do not switch, the AI uses that default workspace. Switching changes the active workspace for the connection until you switch again.

11. Example prompts

Here are examples of prompts you can use once Usermaven MCP is connected.

Read-only questions

"Which channels brought the most signups last month?"
"Which campaigns generated the most paying customers?"
"Where are users dropping off in our onboarding funnel?"
"Which channels generated the most revenue?"
"Compare this month with last month."
"Show me the customer journey before purchase."
"What were my top traffic sources this week?"
"How many sessions did we get from Google last month?"

Workspace switching

"List my available workspaces."
"Which workspace am I currently using?"
"Switch to my Acme workspace."
"Now answer the same question for my Beta workspace."

Write actions (require your approval)

"Create a funnel for signup → trial → purchase."
"Create a conversion goal for a completed checkout."
"Add a tile for [metric] to my weekly dashboard."

12. Read vs. write actions

It is important to understand the difference between actions that only read data and actions that change data.

Read actions

These only retrieve or analyze data. They do not change anything in Usermaven:

Trend, traffic, and session queries.
Segmentation queries and segment lists.
Funnel and journey queries.
Attribution and revenue queries.
Retention and conversion goal queries.
Listing dashboards, reports, views, models, and taxonomy.
Listing and switching workspaces.

Write actions

These create or update something in Usermaven. They always require your approval:

Creating or updating a funnel, conversion goal, segment, journey, retention report, or trend report.
Creating a dashboard or adding a tile to a dashboard.
Creating an attribution view.

If you only want the AI to look at your data, you can decline write permissions during authorization. Even with write permissions enabled, no change happens without your explicit request and approval.

13. Troubleshooting

Connection failed

Make sure you typed the MCP server address correctly:
```
https://mcp.usermaven.com/mcp
```
Check that your AI client supports remote MCP servers.
Try again, or restart the client and reconnect.

Authorization failed

Make sure you are signed into the correct Usermaven account.
If you cannot finish signing in, contact your workspace admin or Usermaven support.

Workspace not visible

The connection only shows workspaces you selected during authorization.
If a workspace is missing, reconnect Usermaven and select that workspace during authorization.
A workspace with MCP disabled by its admin may also be unavailable.

Cannot switch workspace

The AI can only switch to workspaces the connection was authorized for.
If a switch is blocked, reconnect and include the workspace, or ask your admin to grant access.
The target workspace's MCP policy must be enabled.

Permission errors

The connection only has the permissions you approved.
If an action is blocked, the AI is limited to the read/write scopes you allowed.
Reconnect and approve additional permissions if needed, or ask your admin.

MCP tool unavailable

Not all tools are available if you did not grant the matching permission (for example, write tools without write permission).
Make sure the workspace's MCP policy is enabled for the workspace you are using.

Reconnecting the integration

You can disconnect and reconnect the MCP server from your AI client at any time.
Reconnecting starts the authorization flow again, where you can choose workspaces and permissions fresh.

14. FAQ

Can I use Usermaven MCP with ChatGPT?

Yes. Add the Usermaven MCP server address in ChatGPT, then complete Usermaven authorization. See Section 5.

Can I use it with Claude?

Yes. Add the Usermaven MCP server address in Claude, then complete Usermaven authorization. See Section 6.

Can I use it with Cursor or Codex?

Yes. Both support remote MCP connections to Usermaven. See Sections 7 and 8.

Can I access multiple workspaces?

Yes. You select workspaces during authorization and can switch between them on one connection. See Section 10.

Can MCP make changes in Usermaven?

Yes, if you grant write permissions. MCP can create or update funnels, conversion goals, segments, journeys, dashboards, and trend reports. Changes only happen with your explicit request and approval.

Does it require approval before changes?

Yes. Write actions require your approval before they run.

Which data can MCP access?

It can access the workspaces you selected and the data covered by the permissions you approved (analytics, attribution, journeys, funnels, segments, dashboards, and your event taxonomy). It cannot access workspaces you did not select.

Which plans include MCP?

It is included in all plans.

Can agencies use one MCP connection across multiple client workspaces?

Yes, to the extent that you authorize multiple workspaces on the connection. You can switch between the connected client workspaces on a single connection. Each workspace still honors its own admin-controlled MCP policy and permissions.

Need more help?

If something here does not match what you see, or you need help with your specific setup, contact Usermaven support.

Was this article helpful?