Setting Up the UserGuiding MCP Server

Connect your AI assistant to UserGuiding with OAuth or an API key, on the US or the EU server.

Setting Up the UserGuiding MCP Server

This article walks through connecting an AI assistant to your UserGuiding project through the MCP Server: where to find your server URL, how to authenticate with OAuth or an API key, and what changes if your account is hosted on the EU server.

For an overview of what MCP is and what it can do, see UserGuiding MCP Server.

Before you start

MCP is available on all UserGuiding plans.
You need panel access to the project you want to connect. A connection is always scoped to one project.
Setup takes about two minutes. No developer help and no code change in your product are needed.
Your AI client must support remote MCP servers over Streamable HTTP. Claude (web, desktop and Claude Code), Cursor and OpenAI Codex all do.

Step 1: Copy your server URL

In the UserGuiding panel, go to Settings > Project Settings > MCP & API Key. The page shows the server URL for your account plus ready-to-paste snippets for the most common clients.

There are two production servers, one per data region:

US (default): https://mcp.userguiding.com/mcp/
EU: https://eu-mcp.userguiding.com/mcp/

The panel always shows the URL that matches your account's region, so copying it from there is the safest option. If your account is on the EU server, read the EU server support section below before you connect.

Note the trailing slash. The server speaks Streamable HTTP at /mcp/. The old Server-Sent Events endpoints (/mcp/sse and /mcp/messages) have been retired and now answer with 410 Gone. If you set up MCP before this change, update the URL in your client.

Step 2: Choose how you authenticate

The panel offers two tabs, OAuth and API Key. OAuth is the recommended method for every new connection. API key authentication still works but is being retired, and the panel shows a deprecation notice on that tab.

Option A: OAuth (recommended)

With OAuth you never copy a secret into a config file. You add the server URL, and your assistant sends you through a normal UserGuiding sign-in the first time it connects.

What happens when you connect:

Your client registers itself with UserGuiding automatically (dynamic client registration) and opens a browser window.
You sign in with your UserGuiding panel account. If your account enforces two-factor authentication, you complete it here.
A consent screen appears. At the top you pick which project the assistant may access, with your default project preselected. Below it you see the exact permissions the client is asking for.
You approve, and the client receives a token. Access tokens are short-lived (one hour) and refreshed silently in the background, so you do not repeat this flow every session.

Connection snippets:

Claude Code

claude mcp add --transport http userguiding https://mcp.userguiding.com/mcp/

Codex CLI

codex mcp add userguiding --url https://mcp.userguiding.com/mcp/

Cursor and other JSON-config clients

{
  "mcpServers": {
    "userguiding": {
      "url": "https://mcp.userguiding.com/mcp/"
    }
  }
}

Claude.ai and Claude for Desktop

Claude connects to remote servers through custom connectors. On a team or enterprise workspace an admin adds the connector once, then everyone else enables it.

Select your profile icon in the bottom-left corner of Claude, then open Settings (workspace admins: Admin settings).
Open the Connectors tab and click Add custom connector.
Name it UserGuiding and paste your server URL from the panel.
Click Connect, sign in with your UserGuiding account, pick your project and approve the permissions.

Option B: API key (legacy)

API key authentication is still supported for existing setups, but it will stop working. Move connections to OAuth when you can.

Create or copy the key from the User API Key section on the same panel page, then send it in the UG-API-KEY header.

Claude Code

claude mcp add --transport http userguiding https://mcp.userguiding.com/mcp/ --header "UG-API-KEY: YOUR_API_KEY"

Codex CLI (~/.codex/config.toml)

[mcp_servers.userguiding]
url = "https://mcp.userguiding.com/mcp/"
http_headers = { "UG-API-KEY" = "YOUR_API_KEY" }

Cursor and other JSON-config clients

{
  "mcpServers": {
    "userguiding": {
      "url": "https://mcp.userguiding.com/mcp/",
      "headers": {
        "UG-API-KEY": "YOUR_API_KEY"
      }
    }
  }
}

Clients that cannot send custom headers can pass the key as a query parameter, https://mcp.userguiding.com/mcp/?api_key=YOUR_API_KEY. This is a compatibility fallback only. It puts a live credential in a URL that gets stored in config files and logs, so prefer OAuth.

An API key grants every tool with no scope filtering, so treat it like an admin credential. Resetting the key from the panel immediately invalidates every connection using it.

EU server support

UserGuiding runs separate US and EU environments, and each one stores its own customer data. MCP follows the same split: the EU MCP Server is a different host that reads only EU data.

US accounts connect to https://mcp.userguiding.com/mcp/.
EU accounts connect to https://eu-mcp.userguiding.com/mcp/.

Both regions share one sign-in service at api.userguiding.com, so the OAuth experience is identical. What differs is the token: when you approve the consent screen, UserGuiding issues a token bound to your account's region, and each MCP Server only accepts tokens minted for itself. That binding is what keeps EU data inside the EU environment.

Practical consequences:

Always copy the URL from Settings > Project Settings > MCP & API Key rather than from a blog post or an older version of this article. The panel resolves the region for you.
If an EU account points a client at the US URL, the connection fails on the token check rather than silently returning someone else's data.
Team members sharing a config file must all be on the same account, and therefore the same region. There is no combined URL that serves both.
Not sure which region you are on? See Switching to EU server.

Permissions

An OAuth connection carries a set of scopes, and every tool call is checked against them. If a scope is missing, that single tool is refused with a clear message and the rest of the connection keeps working. Requesting fewer scopes is the simplest way to hand an assistant read-only access.

users:read: read end-user profiles, attributes, segments, tracked events and performance analytics for all materials.
users:write: create, update and delete end-users, and reset their UserGuiding history.
events:write: track custom events for end-users.
companies:read: read company profiles and engagement data.
knowledge_base:read: read and search Knowledge Base articles and categories.
knowledge_base:write: create, update and delete Knowledge Base articles and categories.
segments:write: create and update user segments.
product_updates:read: read Product Updates posts.
product_updates:write: create, update and delete Product Updates posts.
roadmap:read: read roadmap items and feature requests.
roadmap:write: approve, reject and manage feature requests.

A client that asks for nothing specific gets the default set: users:read, companies:read, events:write and knowledge_base:read. API key connections bypass scope checks entirely, which is another reason to prefer OAuth.

Whichever method you use, the project is fixed at connection time. The project you picked on the consent screen (or the project the API key belongs to) is the only one the assistant can reach, and no tool argument can change it. Cross-project and cross-account access is not possible.

Limits

Rate limit: 60 tool calls per minute per project, shared by every connection into that project.
Date ranges: analytics tools accept a range of at most one year.
Retention analysis: at most 31 cohorts in one call, so a daily matrix covers 31 days and a weekly one 31 weeks.
Large audiences: per-member breakdowns are refused above 10,000 members, both for segments and for companies. Narrow the segment instead.

When a request would exceed one of these limits, the tool returns an error explaining the limit. It never trims the data silently, because a quietly truncated answer looks authoritative and is wrong.

What gets logged

Every MCP tool call is recorded for roughly three months and used for abuse forensics and troubleshooting. Writes go one step further: creating an article, updating a segment or approving a feature request is recorded in the panel Activity Log with the name of the panel user behind the connection, exactly as if they had made the change by hand.

Troubleshooting

410 Gone, or "Legacy SSE transport is not supported": your client still points at /mcp/sse. Change the URL to https://mcp.userguiding.com/mcp/ (or the EU host) and reconnect.
401 Unauthorized: the token was issued for the other region, expired, or the API key was reset. Remove the connection in your client and add it again.
"Missing Authorization header or UG-API-KEY": the client is not sending credentials at all. On JSON clients, check that the header block sits inside the server entry.
"Insufficient scope": the connection was approved without the permission that tool needs. Reconnect and approve the missing scope.
The assistant answers, but the numbers look empty: you probably picked the wrong project on the consent screen. Reconnect and select the right one.
Sudden burst of errors during a long analysis: you hit the per-minute rate limit. Ask the assistant to work in smaller batches.

Next steps

UserGuiding MCP Tool Reference: every tool and the permission it needs.
UserGuiding MCP Use Cases and Example Prompts: prompts to copy for your team.