Lens MCP tools

Registered when the server starts with LENS_API_URL set. 25 tools, listed with the description the server sends in tools/list.

Tool	Description
lens_create_project	Create a Lens project and return its install snippet. The secret key is returned ONCE and can never be retrieved again.
lens_declare_funnel	Declare an ordered funnel: 2-8 event names plus how many hours after the first step a later one still counts.
lens_delete_funnel	Delete a declared funnel. A funnel accrues only from the day it was declared, so re-declaring the same steps later starts from THAT day rather than resuming this one’s history.
lens_delete_person	Erase every event belonging to one person in a project, and the receipts naming them. Irreversible; this is how a data-subject erasure request is answered. Workspace owners and admins only (403 admin_required).
lens_delete_project	Delete a Lens project. Its keys stop working immediately and it stops collecting.
lens_file_issue	Open a Space issue for an error group, carrying its occurrence count, affected visitors and newest stack. Filing twice returns the existing ticket instead of opening a second one.
lens_get_alerts	How this project alerts on defects, and whether an alert would actually be DELIVERED — a destination Connect cannot reach looks identical to a working one until the first defect nobody hears about.
lens_get_breakdown	WHICH ones. Group a project’s events by one dimension and get the top values — which products people looked at, which pages, which releases, or what they are doing at all (by: name), or WHO is here (by: person). This is the only way to answer ‘which’, because paths are templated to protect the rollups: every product page is stored as /p/:id, so the identity lives in the event’s properties. Pass a column (name, path, referrer_host, country, device_class, source, person) or any property as p.<key>, e.g. by: ‘p.product_name’. Reads raw events, so it reaches back only as far as the project’s retention window. untagged counts events missing the dimension — when it is not zero it usually means a broken install.
lens_get_error	One error group in full, including the RING OF RECENT SAMPLES — each with the message, stack, path and release of a single occurrence. This is the tool that can diagnose a defect; lens_list_errors only says which one to look at. Stacks are NOT symbolicated, so a production frame reads like main-4f3a.js:1:28471. regression_candidate means the defect was seen again after being resolved.
lens_get_preview_insights	What happened in one preview environment: how many people opened it, what they did, and what broke. Nobody having opened it is a FINDING for a reviewer, not missing data.
lens_get_project	Get one Lens project: public key, retention, identity mode, and when it last received an event.
lens_get_retention	Of the people first seen on a day, how many came back. REFUSES with a reason on projects whose device ids rotate daily — the question is unanswerable there, not merely noisy, and a flat line would be a false claim. Never report a refusal as zero.
lens_get_segment	Narrow a project to one slice of traffic by any property the events carry — release, plan, country, experiment, preview_id. Visitor counts here are EXACT rather than approximate, because a slice is small enough that a sketch’s error would exceed the number.
lens_get_trends	Events and unique visitors per day for a project. Unique counts are a UNION across the range, never a sum of the daily figures, and they are approximate by design — say so when reporting them.
lens_get_usage	A workspace’s Lens event usage this month, its limit, and whether the quota is recording or enforcing. In record mode nothing is refused.
lens_list_errors	Grouped software defects: one row per distinct defect with its occurrence count, how many visitors it reached, and the newest stack. The visitor count is approximate. A REGRESSED group was resolved and came back, which is more urgent than a new error, not less.
lens_list_events	Read a Lens project’s most recent events, newest first. Pass person_id to read what ONE person did, or key+value to read one slice of traffic.
lens_list_funnels	The funnels DECLARED on a project. A funnel accrues only from the day it was declared and reads raw events, so it has no history before then and cannot reach past the retention window.
lens_list_projects	List the Lens projects in a workspace, with whether each has ever received an event.
lens_resolve_error	Mark an error group handled. It is KEPT rather than deleted: if the defect happens again it is reported as a regression, which is only possible because the row survived.
lens_rotate_keys	Mint a new key pair. The old keys stop working IMMEDIATELY — there is no grace period, because rotation is what you do when a key has leaked.
lens_run_funnel	Run a declared funnel and report how many people reached each step.
lens_send_test_event	Store one synthetic event, to prove the pipe without touching the customer’s app. It proves the authenticated control plane and the store; it does NOT prove their snippet is running, their key resolves, or CORS — the first browser event confirms those. Say that difference when reporting it.
lens_set_alerts	Send a message through this workspace’s own connected app when a defect is FIRST SEEN, or when one that was resolved comes back. Repeat occurrences of a known defect are never sent. daily_cap is required and bounded 1-200: the public ingest key sits in the customer’s page source, so unlimited alerts would let a stranger page the team all night. Zero is NOT unlimited — use enabled:false.
lens_update_project	Change what a customer owns on a Lens project: its name, how many days of raw events it keeps (1-90), whether it identifies visitors persistently, and whether it is collecting at all. identity_mode ‘persistent’ stores an id in a visitor’s browser — a consent obligation the customer takes on, and the only mode under which retention can be answered. Shortening retention_days DELETES raw events past the new window on the next sweep.