Skip to main content
Glama
arttus

umami-mcp-server

by arttus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Get funnel conversion across ordered steps

umami_get_funnel
Read-onlyIdempotent

Analyze user funnels by passing an ordered sequence of page paths or custom events to get session counts per step and drop-off rates between steps.

Instructions

Get session counts and drop-off across an ordered sequence of pages and/or custom events.

Umami has no funnel endpoint, so this walks every session's activity trail in the range (capped by max_sessions) looking for the steps in order. A step matches a page path or a custom event name, whichever it equals; a session only advances once it has completed the previous step.

Args:

  • website (string, optional): Website ID, name, or domain.

  • steps (string[], required): 2-8 steps in order, each a page path (e.g. '/pricing') or event name (e.g. 'signup').

  • range (string): Date range, default '7d'.

  • start_date / end_date (string, optional): Explicit bounds, overriding 'range'.

  • filters (object, optional): Segment filters applied to the session pool, e.g. { device: 'mobile' }.

  • max_sessions (number): Cap on sessions scanned, default 500, max 2000.

  • response_format ('markdown' | 'json'): Output format (default: 'markdown').

Returns: JSON shape: { "steps": [ { "step": string, "sessions": number, "pct_of_first": number, "pct_of_previous": number } ], "scanned_sessions": number, "total_sessions_in_range": number, "truncated": boolean }

Examples:

  • "Funnel from pricing to signup to activation" -> steps=["/pricing", "/signup", "activation"]

Error handling:

  • If 'truncated' is true, total sessions in the range exceeded max_sessions; raise it for a more complete picture, at the cost of more API calls.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
rangeNoDate range for the query, default '7d'. Relative ("30m", "24h", "7d", "4w", "3mo", "1y"), named ("today", "yesterday", "this_week", "last_week", "this_month", "last_month", "this_year", "last_year", "mtd", "ytd", "all_time"), or an explicit ISO date via start_date/end_date.
stepsYesOrdered steps: page paths or event names.
filtersNoOptional segment filters. Supported keys: path, referrer, title, query, browser, os, device, country, region, city, language, hostname, tag, event, distinctId, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, segment, cohort. Example: { country: 'US', device: 'mobile' }.
websiteNoWebsite ID (UUID), name, or domain. Optional if UMAMI_DEFAULT_WEBSITE is set. Use umami_list_websites to discover values.
end_dateNoExplicit end date (YYYY-MM-DD, ISO 8601 timestamp, or epoch ms). Overrides 'range'.
start_dateNoExplicit start date (YYYY-MM-DD, ISO 8601 timestamp, or epoch ms). Overrides 'range'.
max_sessionsNoMaximum sessions to scan. Higher is more accurate but slower (one extra API call per session).
response_formatNoOutput format: 'markdown' for a readable summary, 'json' for raw structured data.markdown

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the readOnly/idempotent annotations by explaining that Umami has no funnel endpoint, that sessions are walked individually, that scanning is capped by max_sessions, and that truncated results may need a higher cap. It also discloses the cost of higher caps (extra API calls per session) and defines truncation behavior clearly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections for args, returns, examples, and error handling, and it front-loads the core purpose. It is longer than necessary partly because it repeats some schema descriptions, but the additional behavioral context earns the length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, yet the description provides the full JSON return shape, explains truncation semantics, includes an example, and documents error handling. Given the tool's complexity and the absence of structured output metadata, the description is sufficiently complete for an agent to invoke and interpret results correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents parameters well. The description adds meaningful semantics beyond the schema, especially the matching rule for steps, the session-advancement logic, and the practical trade-off of max_sessions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: get session counts and drop-off across an ordered sequence of pages and/or custom events. It is specific about the verb and resource, but it does not explicitly distinguish itself from siblings like umami_get_journeys or umami_get_retention.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when this tool is appropriate — when a funnel-style ordered conversion analysis is needed — and includes an example mapping a user request to steps. It does not, however, name alternative tools or give explicit when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools