Secure Userpilot access for AI agents
Product analytics, user and company profiles, session replays, segments, reports, dashboards, and surveys via Userpilot's official MCP server
Userpilot lets your agents answer questions about how people use your product. They can run trend, funnel, retention, and path reports, look up the end users and companies Userpilot tracks, read session replays, and build segments, dashboards, and surveys. Every call runs through your policies and is logged for audit.
Server URL: https://mcp.userpilot.io/mcp
Userpilot installs with write access
Userpilot installs with permission to write, not only to read. Agents can create and update segments, reports, dashboards, and surveys. Surveys save as drafts, but segments, reports, and dashboards take effect at once. Decide your policy before you let people connect.
Credential modes
Userpilot supports per-org dynamic registration only, so there is no app to create on Userpilot's side and no client ID or secret to enter. See Credential modes for how it compares with Use SecureAuth's app and Bring your own app.
Before you begin
- A Userpilot account on a plan that includes MCP access, with access to the workspace your agents should reach.
- Administrator access to your Agent Authority workspace.
- A decision on whether agents may write into Userpilot. See Policy examples.
- If Userpilot is already registered here as a custom MCP server, remove it first. Both would claim the
userpilotslug.
Setup
- In the Agent Authority console, go to Tools & Services and click Add Resource.
- Select Userpilot from the catalog.
- On Choose how to install Userpilot, click Per-org dynamic registration. Selecting it adds the resource right away, with its 25 tools pre-configured and no credentials to paste.
After you add the resource, an Admin setup required dialog appears. Its Setup guide button links to the section below.
Dynamic client registration
When you add the resource, the gateway registers its own OAuth client with Userpilot, the credential it uses to sign users in. Userpilot issues it automatically, so you configure nothing on the Userpilot side.
Your policies are not the only limit. Each user's Userpilot roles still apply, so an agent can never do more than that person could do in Userpilot itself.
Every user chooses their own permissions
Userpilot's consent screen is a checklist, not a single approve button. Reading product data is always granted. The other five permissions (profiles, session replays, segments, reports, and surveys) are separate checkboxes a user can clear before approving. The same policy can therefore succeed for one person and fail for another. When a replay or profile call is refused, check the granted scopes on that user's connection before you change policy.
Which workspace the agent reads. Userpilot calls a product environment a workspace, and one account can hold several. Most tools take an application_id, which is a workspace id, and agents find them with list_workspaces. If you have more than one, tell users which to work in: wrong data usually means the wrong workspace.
Verify the connection
The gateway syncs the Userpilot tools automatically. To check the connection end to end, ask your agent to run a request:
List my Userpilot workspacesIf your workspaces come back with their access and default flags, the connection is working. If a call is refused, see Troubleshooting.
How users connect
Access is per user. Each person links their own Userpilot account once:
- Open the Userpilot resource and click Connect.
- Sign in at Userpilot and approve the consent screen. Leave every permission checked unless you mean to withhold one.
- Userpilot returns you to Agent Authority, and the connection shows Connected.
Consent cannot be edited afterwards. To change what a user granted, delete the connection and connect again. Go to Connections to manage linked accounts.
Available tools
25 tools: 15 read and 10 write. Two of them, search_tools and describe_tool, reach the rest of Userpilot's API beyond this table.
| Tool | Tags | Description |
|---|---|---|
list_entities | read-only | List entities of one type as normalized {id, name, ...} items |
get_entity | read-only | Fetch one entity by type and id |
list_users | read-only | Search and filter the end users Userpilot tracks |
get_user | read-only | Fetch one end user's analytics profile by user id |
list_companies | read-only | Search and filter the companies Userpilot tracks |
get_company | read-only | Fetch one company's analytics profile by company id |
run_report | read-only | Run an analytics report and return computed numbers |
list_reports | read-only | List saved report definitions, not results |
get_report | read-only | Fetch a saved report's definition, to pass to run_report |
list_dashboards | read-only | List the workspace's dashboards |
get_dashboard | read-only | Fetch a dashboard's reports and layout |
list_workspaces | read-only | List your workspaces with access and default flags |
search_tools | read-only | Search Userpilot operations beyond the core tools |
describe_tool | read-only | Return the full input schema of a tool or operation |
execute_operation | read-only | Execute one read operation found through search_tools |
create_segment | write | Create a segment of end users |
update_segment | write | Update fields of an existing segment |
create_report | write | Create a saved report definition |
update_report | write | Update fields of an existing saved report |
create_dashboard | write | Create a custom dashboard |
update_dashboard | write | Update a dashboard |
create_survey | write | Create a survey, saved as a draft |
update_survey | write | Update fields of an existing survey |
create_survey_module | write | Add a module (question or step) to a survey |
update_survey_module | write | Update a module of a survey |
Required scopes
The gateway requests these automatically, so there is nothing for you to configure. data:read is always granted; the user approves the rest on the consent screen.
data:read– product data, analytics, and reportspeople:read– end user and company profilessessions:read– session replay datasegments:write– create and update segmentsreports:write– create and update reports and dashboardsfeedback:write– create and update surveys, saved as draftsoffline_access– refresh a user's access token without a new sign-in
Policy examples
Every org starts with an Allow all rule at the bottom of the policy list. Because of it, a resource you just added is reachable as soon as someone connects, write tools included. Rules are read from the top, and the first one that matches wins. Adding more allow rules changes nothing, so each example below works by adding a deny above that Allow all rule.
Userpilot names every write tool create_* or update_*, so the common recipes are short:
- Read-only analytics. Deny
create_*andupdate_*. Those two globs cover the whole write surface, andexecute_operationis reads-only by design. - Analytics without personal data. Deny
list_users,get_user,list_companies,get_company, and the replay tools. Aggregate reporting throughrun_reportkeeps working. - Block session replays only. Deny the replay tools, leaving profiles and reporting intact. A user can also withhold
sessions:readat consent time, which has the same effect for that one person. - No customer-facing surveys. Deny
create_survey,update_survey,create_survey_module, andupdate_survey_module. Surveys are saved as drafts and still need a person to publish them, so this rule is a second layer rather than the only guard.
Next steps
- Create a policy – start from the read-only pattern in Policy examples above.
- Policies – how first-match-wins rule order and the seeded Allow all rule interact.