UserGuiding MCP Server
Connect your AI tools directly to your UserGuiding project through the MCP Server. Once connected, tools like Claude, Cursor, or any MCP-compatible assistant can look up users, search by attributes or events, track events, manage companies, manage Knowledge Base articles, and more — all through natural language.
How It Works
The MCP (Model Context Protocol) is an open standard that lets AI tools call external services in a structured, safe way. The UserGuiding MCP Server exposes your project's user data as a set of tools the AI can invoke on your behalf.
AI Tools (Claude, ChatGPT, etc.)
│
│ SSE connection + JSON-RPC messages
▼
UserGuiding MCP Server
│
│ Authenticated via your API key
▼
Your UserGuiding Project Data
Getting Started
Step 1: Get Your API Key
Find your API key in UserGuiding Panel → Settings → Project Settings → MCP & API.
Step 2: Connect Your AI Tool
The MCP Server uses Server-Sent Events (SSE) as its transport. Add the following to your AI tool's MCP settings:
Server URL:
https://mcp.userguiding.com/mcp/sseAuthentication — pass your API key as a header:
UG-API-KEY: <your-api-key>Or as a query parameter (for tools that don't support custom headers):
https://mcp.userguiding.com/mcp/sse?api_key=<your-api-key>Claude.ai and Claude for Desktop
For both claude.ai and Claude for Desktop, an admin must first add the UserGuiding MCP Server as a connector before other Claude users can connect.
- Select your profile icon in the bottom-left corner of Claude, then select Admin settings.
- Open the Connectors tab, then click on the (+) icon on the top of the Connectors field.
- Choose Add Custom Connector:
- Name: UserGuiding
- Remote MCP Server URL: https://mcp.userguiding.com/mcp/sse
- Click "Connect" to authenticate and start using the connector with Claude.
Configuration Examples
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"userguiding": {
"url": "https://mcp.userguiding.com/mcp/sse",
"headers": {
"UG-API-KEY": "<your-api-key>"
}
}
}
}
Cursor (.cursor/mcp.json):
{
"mcpServers": {
"userguiding": {
"url": "https://mcp.userguiding.com/mcp/sse",
"headers": {
"UG-API-KEY": "<your-api-key>"
}
}
}
}
Available Tools
User Management
get_user
Look up a user by ID. Returns all attributes, company association, and interaction history.
upsert_user
Create a new user or update an existing one. Merges attributes and optionally attaches the user to a company.
delete_user
Permanently delete a user.
reset_user_history
Reset a user's interaction history (guide views, checklist progress, etc.) while keeping their custom attributes.
list_users
List all users with cursor-based pagination.
Search & Analytics
search_users
Search and filter users by attributes or events. Supports pagination and sorting.
get_user_count
Count users matching filters without fetching full user data.
list_attributes
Discover all available user attributes and their data types.
list_events
Discover all tracked event names in your project.
Events
track_event
Track a named event for a user, optionally with metadata.
Companies
get_company
Look up a company by ID. Returns attributes and member user IDs.
list_companies
List and filter companies with pagination and sorting.
Knowledge Base
search_kb_articles
Search your Knowledge Base articles by text query. Returns article IDs, titles, descriptions, and categories ranked by relevance.
get_kb_article
Retrieve the full content of a Knowledge Base article by its ID, including title, body, description, publish status, and all locales.
create_kb_article
Create a new Knowledge Base article with a title, content, and optional description.
update_kb_article
Update the title or content of an existing Knowledge Base article by its ID.
delete_kb_article
Permanently delete a Knowledge Base article by its ID.
Searching and Filtering Users
The search_users tool supports two types of filters.
Attribute Filters
Filter users by any built-in or custom attribute:
{"attribute": "email", "equation": "contains", "value": "@acme.com"}
{"attribute": "plan", "equation": "equals", "value": "enterprise"}
{"attribute": "first_seen", "equation": "after", "value": 1704067200000}
Available equations by attribute type:
Text
equals, not_equals, contains, not_contains, starts_with, ends_with, regexp, is_not_known, has_any_value
Number
equals, not_equals, more_than, less_than, is_known, is_not_known
Date
before, after, equals, not_equals, more_than_days_ago, less_than_days_ago, exact_days_ago, is_not_known, has_any_value
Boolean
equals, not_equals, is_not_known, has_any_value
Event Filters
Filter by whether a user has (or has not) performed an event:
{"event": "signed_up", "equation": "has_done"}
{"event": "export_csv", "equation": "has_not_done"}
Available equations: has_done, has_not_done
Combining Filters
Pass multiple filter objects in the filters array. Filters are combined with AND logic:
[
{"attribute": "plan", "equation": "equals", "value": "enterprise"},
{"event": "export_csv", "equation": "has_done"}
]
Example Prompts
Once connected, here are some prompts your team can use:
- "How many users signed up in the last 7 days?"
- "Find all users on the enterprise plan whose last seen date is before January 2025."
- "Show me the details for user u_abc123."
- "Track a plan_upgraded event for user u_abc123."
- "List all companies with more than 50 members."
- "Search the knowledge base for articles about getting started."
- "Find all knowledge base articles in the Developers category."
- "Show me the full content of knowledge base article 182."
- "Create a new knowledge base article titled 'How to use the REST API' with a short introduction."
- "Update article 299 to mention that the new indexing options are available."
FAQ
What data can the MCP server access? The MCP server can only access data within the project associated with your API key. It cannot access other projects or other accounts.
Is the connection secure? Yes. All communication is over HTTPS, and your API key authenticates every request.
Is there a rate limit? The MCP server follows the same rate limits as the UserGuiding Public API.