Advice and answers from the UserGuiding Team
Users
Engagement
Settings
UserGuiding MCP Tool Reference
Every tool the UserGuiding MCP Server exposes, what it does, and the permission it needs.

💡 You can visit https://developers.userguiding.com/ for more up-to-date information about this topic and developer documentation.


UserGuiding MCP Tool Reference

The UserGuiding MCP Server exposes 71 tools across eleven 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. Through Lighthouse AI it only updates existing users and lists any unknown ids instead of creating them, unless you confirm the creation first. (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)
  • get_event_breakdown: occurrences and unique users of one event grouped by up to three fields, such as url_host, url_path, browser or device, or any metadata key like guide_id and step for element_not_found. Filters accept exact values or a prefix (for example every /reporting/ page), and exclusive_users tells you how many users had the event only inside the filter. This answers "where does this event happen" without reading user activities one by one. Unique-user counts are approximate. (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)

Banners

  • get_banner_create_options: the project's themes and containers, with the defaults marked, and the layout defaults a new banner gets. The assistant reads it before asking you for banner details. (users:read)
  • get_banner: one banner's full configuration, including its schedule, theme and container names, and the translation status of each language (missing or needs review). (users:read)
  • open_banner_form: shows the banner, already filled in from your request, as a form in the chat for you to review and submit. Clients that cannot show forms get the configuration as text instead. (users:read)
  • create_banner: create a banner from the pages it should appear on, its text (up to 199 characters) and up to two buttons. Settings you leave out get the panel's defaults (inactive, all users, shown on page load, floating at the top), and the assistant tells you which defaults it applied. (materials:write)
  • update_banner: change only the fields you name. Schedule, segments, theme, container and translations are kept. Changing the text or a button label marks its translations as needing review. (materials:write)
  • translate_banner: translate a banner's text and button labels into one language with UserGuiding's auto-translate, sharing the panel's daily auto-translate quota. Needs localization on your plan. A language the project does not have yet is added only after you confirm. (materials:write)
  • delete_banner: permanently delete a banner and its translations. Account owners and admins only. (materials:write)

Banners written through MCP are saved as pending changes, and new banners start inactive. They reach your users only after someone publishes from the panel.

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)

AI Assistant and Ask AI chats

  • list_ai_assistant_chats: list the chat threads users had with an AI chatbot, newest first. The source option picks the chatbot: the in-app AI Assistant (the default) or Ask AI on the Knowledge Base. Filter by user or email, date range (at most one year), chats that ended in a fallback, resolution (AI Assistant only: resolved, unresolved or pending), likes or dislikes, and words in the user's messages. Each row has a thread_id, the user's first message and the outcome flags. Results come in pages of up to 50 with a cursor. (users:read)
  • get_ai_assistant_top_questions: the most asked opening questions for the AI Assistant or Ask AI over a window of up to one month, counted in one call. Wordings that differ only in case, accents, punctuation or spacing are merged; the assistant then combines groups that mean the same thing and tells you which ones it merged. At most 60 groups are returned. (users:read)
  • get_ai_assistant_chat: one conversation in full. Returns the outcome flags and a timeline of every message with its text, whether it was a fallback, the user's like or dislike, and the articles, guides or fallback actions the answer used. For the AI Assistant it also shows the guides the assistant started and the articles the user opened from it. Very long threads are cut at the first 200 messages. Take the thread_id from list_ai_assistant_chats. (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. If the Knowledge Base page exists but no language has been activated yet, the first category also activates the page with the requested language (English by default) as its default language. Adding further languages stays a panel action. (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. If the Product Updates page exists but has no language yet, the first post activates it with the requested language (English by default) as its default language. (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

Five tools are irreversible: delete_user, reset_user_history, delete_kb_article, delete_product_updates_post and delete_banner. 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

Did this answer your question?
Ask AI
Responses are generated using AI and may contain mistakes.
How can I help you?
Ask me anything about our product. I can help you find answers across the knowledge base.
Ask a question...Ctrl+I