UserGuiding MCP Tool Reference

The UserGuiding MCP Server exposes 58 tools across nine areas. You never call them by hand: you ask a question in plain language and your assistant picks the tools it needs, often chaining several in one answer. This page is the map, so you know what is possible and what to ask for.

Each entry lists the permission (scope) the tool needs on an OAuth connection. See Setting Up the UserGuiding MCP Server for how scopes are granted.

How the tools fit together

• Discovery first. Attribute names, event names, material names and segment names are project-specific, so the assistant usually starts with a listing tool (list_attributes, list_events, list_materials, list_segments, list_kb_categories) before it filters anything.
• Names or ids. Analytics tools accept a material by name (case-insensitive) or by id. If a name matches more than one material, the tool returns the candidates so the assistant can retry with the right id.
• Deleted entities are labelled, not hidden. Analytics rows whose guide, checklist item, hotspot or button no longer exists come back flagged as deleted, with their historical counts intact.
• Dates are inclusive and every analytics range is capped at one year.

Users and attributes

• get_user: full profile for one user, with attributes, company and aggregated interaction history. (users:read)
• list_users: page through users with a cursor. Ask for specific fields to keep responses small. (users:read)
• search_users: filter users by attributes or by event behaviour, with per-type equations (contains, more_than, more_than_days_ago, and so on). (users:read)
• get_user_count: count the users matching a filter set without fetching any of them. The fastest way to size an audience. (users:read)
• list_attributes: every filterable user and company attribute with its data type. (users:read)
• get_user_activities: raw activity feed for one user, newest first, optionally narrowed to page views, material interactions or custom events. (users:read)
• list_users_by_event: who performed a given event. A shortcut for the common "who did X" question. (users:read)
• upsert_user: create a user or merge attributes into an existing one, optionally attaching them to a company. (users:write)
• delete_user: permanently delete a user. (users:write)
• reset_user_history: clear a user's UserGuiding interaction history while keeping their custom attributes, so they see onboarding content again. (users:write)

Events and product analytics

• list_events: every tracked event name with its context (default, custom user event, custom triggered event). (users:read)
• count_events: how many times an event fired in a date range. Pure volume. (users:read)
• get_event_timeseries: occurrences and unique users bucketed by day, week or month, with empty buckets included so trends have no gaps. (users:read)
• analyze_feature_adoption: adoption depth for one event: adopters, adoption rate against the whole user base, events per adopter, active days and stickiness. Use it whenever the question is about people rather than raw volume. (users:read)
• analyze_retention: cohort retention matrix. Users are grouped by when they were first seen, then tracked forward, with a weighted average curve. Optionally scoped to a segment or to one specific event. (users:read)
• track_event: record a custom event for a user, optionally with metadata. (events:write)

Segments

• list_segments: the project's segments with their ids and member counts, and whether each count is live or an activity-window figure. (users:read)
• get_segment_performance: engagement counts for every material targeted to one segment, all material types in a single call. (users:read)
• get_segment_user_interactions: for an attribute-based segment, which members interacted with which materials in a date range, broken down by event. This answers "what did these people actually do", as opposed to what was aimed at them. (users:read)
• create_segment: build a saved segment from a natural-language description. Attribute filters, event filters and material interaction filters can be mixed, including AND/OR groups. (segments:write)
• update_segment: rename a segment or replace its filters. Built-in segments cannot be edited. (segments:write)

Companies

• get_company: one company with its attributes and member user ids. (companies:read)
• list_companies: companies with pagination, sorting and attribute filters. (companies:read)
• get_company_engagement: engagement health for one account: active members, active member rate, interaction totals, the same figures for the previous period, and which materials its members used. The previous-period block is the declining-usage signal for CS teams. (companies:read)

Material analytics

• list_materials: every guide, survey, checklist, banner, hotspot group, resource center and Product Updates post with ids and names. (users:read)
• get_material_performance: engagement counts over a date range, for one material or for every material of a type at once. The bulk mode is how ranking and top-N questions get answered in one call. (users:read)
• get_project_overview: project-wide totals per metric, a trend comparison between the two halves of the range, and a daily series. The best starting point for "how are we doing". (users:read)
• get_goal_performance: how many times each goal was reached, including goals nobody reached, so "nobody hit it" is distinguishable from "it does not exist". (users:read)
• get_guide_step_funnel: per-step funnel for one guide: unique users who reached each step, plus plays and completions. This is where drop-off shows up. (users:read)
• get_user_guide_progress: per-user progress inside one guide, with the furthest step each user reached. (users:read)
• get_checklist_item_stats: per-item interactions and unique users for a checklist, plus its overall completion rate. (users:read)
• get_hotspot_stats: per-hotspot interactions, button clicks, dismissals and unique users inside a hotspot group. (users:read)
• get_banner_click_stats: per-button click counts for a banner, with the banner's overall click total so per-button rates can be computed. (users:read)
• get_resource_center_tab_stats: views and unique users per resource center tab, including enabled tabs with zero views. (users:read)

Surveys

• get_survey_report: the full report for one survey in a single call: views, responses, response rate, and every question in order with its score distribution, choice counts or feedback count, plus drop-off between questions. (users:read)
• list_survey_responses: individual submissions, newest first, one entry per question. This is the source of truth for response history and the way to read free-text answers. (users:read)

Knowledge Base

• search_kb_articles: full-text search across your articles, ranked by relevance. (knowledge_base:read)
• get_kb_article: full content of one article, including publish status and every locale. (knowledge_base:read)
• list_kb_categories: the whole help center structure, categories and sub-categories with their ids and per-language titles. An empty title means that language has no translation yet. (knowledge_base:read)
• detect_kb_platform: detect which help-center platform (HubSpot, Zendesk, Intercom, Freshdesk, Help Scout, GitBook) hosts a domain. The first step of a migration, so the assistant knows how the source content is structured. (knowledge_base:read)
• create_kb_article: create an article with a title, body and optional description, filed into a category or sub-category. (knowledge_base:write)
• update_kb_article: change an article's title, body, description or filing. (knowledge_base:write)
• delete_kb_article: permanently delete an article. (knowledge_base:write)
• create_kb_category: create a top-level category. It is created in every language, but only the language you write in gets a title, so the others need filling in. (knowledge_base:write)
• update_kb_category: rename or restyle a category, one language at a time. (knowledge_base:write)
• create_kb_sub_category: create a sub-category inside a category. Knowledge bases are exactly two levels deep. (knowledge_base:write)
• update_kb_sub_category: rename a sub-category or move it under a different category. Moving it refiles every article inside it. (knowledge_base:write)
• assign_kb_articles: file up to 50 existing articles into a category or sub-category in one call. Articles are moved, not copied. (knowledge_base:write)

Articles written through MCP are saved as drafts. Someone with publish permission still has to hit Publish in the panel, so an assistant can never put content live on your help center by itself.

Product Updates

• list_product_updates_posts: existing posts, newest first, with their content, labels and per-language publish state. Worth calling before writing a new one so the tone and structure match. (product_updates:read)
• create_product_updates_post: create a post from HTML. It is saved as a draft for you to publish from the panel. (product_updates:write)
• update_product_updates_post: edit a post. Changes to an already published post are stored as a pending draft. (product_updates:write)
• delete_product_updates_post: permanently delete a post and all its translations. (product_updates:write)

Roadmap and feature requests

• get_roadmap_overview: counts per moderation state plus the roadmap's status columns and categories, in one call. The place to start. (roadmap:read)
• list_feature_requests: requests filtered by state: pending is the New/Inbox tab, approved is the accepted backlog, rejected is Spam. Vote and comment counts are live. (roadmap:read)
• get_feature_request: one request in full, including its translations. (roadmap:read)
• list_roadmap_items: the requests published on the public roadmap board, in their column order. (roadmap:read)
• approve_feature_request: move a pending request into the approved backlog and onto the public roadmap. (roadmap:write)
• reject_feature_request: move a request to the Spam tab and keep it off the public roadmap. (roadmap:write)

Tools that change or remove data

Four tools are irreversible: delete_user, reset_user_history, delete_kb_article and delete_product_updates_post. They are marked as destructive in the tool catalog, so well-behaved assistants ask for confirmation before calling them. Keeping write scopes off a connection you only use for analysis is the stronger protection.

Related articles

• UserGuiding MCP Server
• Setting Up the UserGuiding MCP Server
• UserGuiding MCP Use Cases and Example Prompts