Hoot Lens

@hootlens/mcp

The Hoot Lens MCP server. It lets an AI assistant (Claude, Cursor, VS Code, Codex and other MCP clients) read what Hoot Lens recorded on your websites: visits, replays, heatmaps, funnels, traffic, findings and changes. The assistant sees only what your own Hoot Lens account can see, and only the sites (projects) and scopes you allow.

Version 1.5.0 is published with improvement review, durable finding work, exact source-context inspection, and npm provenance. Its release record binds the reviewed public source, Linux/Windows Node 20/22 validation, attestation, isolated SDK checks, and active official Registry entry. The hosted service releases separately.

Version 1.4.1 is published with first-website setup recovery, consent-aware installation guidance, and npm provenance. Its release record links the reviewed public source, Linux/Windows Node 20/22 validation, attestation, and installed-package checks. The hosted service releases separately.

A valid connection with no websites returns an empty list and a setup link. Installation guidance keeps website editing access, visitor consent, and received recordings separate.

You can run it two ways:

• Locally over stdio with npx -y @hootlens/mcp (this package), for clients that can launch a stdio server.
• Hosted at https://mcp.hootlens.com/mcp, for clients that support remote MCP servers. Nothing to install; you sign in with Hoot Lens in your browser.

The tool catalog depends on the release and selected toolsets. Source 1.4.0 keeps customer tools discoverable before their optional permissions are granted. Discovering a tool grants no access: the API checks the credential, current site permissions, and requested action every time. Earlier releases may hide tools whose scopes are missing. Check the installed version and inspect tools/list on your actual connection. whoami is available as a CLI command and an MCP connection-check tool; doctor requires 1.2.0 or later.

The read toolset includes explain_snags. When the site has AI explanations enabled, a request can send aggregated counts to the explanation provider and use the site owner's monthly account AI allowance. Inspect its tool description before requesting explanations. Doctor reports this caveat without calling the tool.

Review improvements and track a fix

review_improvements combines control snags, JavaScript errors, and funnel drop-offs with their actual count units, evidence windows, source coverage, and investigation steps. Source identities preserve page versions, revisions, variants, and devices. Replay moments require replay access and a retained recording.

list_finding_work and get_finding_work read saved decisions separately from current evidence. With explicit authorization and read plus annotation permission, update_finding_work can assign, snooze, dismiss, reopen, save a GitHub reference, or record a fix already deployed. list_finding_assignees returns eligible site teammates without email addresses. Revision checks protect concurrent work, and identical operation retries do not create a second change marker.

A saved GitHub link does not create an issue or establish merge or deployment. A reported deployed fix remains separate from the before-and-after outcome report, which states its own scope and sample limits. Source context and evidence windows can be passed to error and funnel inspection, including ordered funnel goal definitions. The API applies the current site permissions on every request.

Requirements

• Node.js 20 or newer (local server only).
• A Hoot Lens account. Reading recordings needs a reachable site. A new owner can add their first website during connection, then approve access to that site. Letting an assistant create additional sites requires separate, explicit OAuth sites:create permission and a release containing create_site.

Sign in

Pick one.

Browser sign-in (recommended). Run this once:

npx -y @hootlens/mcp login

Your browser opens Hoot Lens. Choose the projects and permissions to share, and approve. The sign-in is saved in the macOS Keychain, the Linux Secret Service (libsecret), or, where those are not available, a file (~/.config/hootlens-mcp/credentials.json, or %APPDATA%\hootlens-mcp\credentials.json on Windows). On POSIX systems the fallback uses owner-only mode flags. On Windows it relies on inherited profile ACLs; the package does not enforce an owner-only Windows ACL. Tokens are never printed.

If you have no site yet, enter your website in the connection screen. Creating that website and approving the assistant's access are separate decisions. You can share only the new site with read/replay access; account-wide permission to create future sites is optional. After returning to the assistant, ask it to retrieve the installation instructions for your platform. A connected account and a created site do not establish that the tracking tag is installed or receiving data.

Continue installation at website setup whenever you return. A ChatGPT connection can retrieve Hoot Lens instructions and evidence, but it cannot edit your website by itself. Use a coding agent with authorized repository access, install through your CMS, or hand the instructions to your developer. For a site requiring consent, connect an explicit recording choice before verifying that a recording arrives. Consent platform categories must expressly cover replay; analytics consent alone is not sufficient.

npx -y @hootlens/mcp whoami   # who is signed in, scopes, projects, token expiry

npx -y @hootlens/mcp logout # delete the saved sign-in and end it at the server

login --scopes read,replay asks for fewer permissions (default: read replay annotate). On a remote machine without a browser, login prints the link; open it on a machine that can reach the CLI on 127.0.0.1 (for example through an SSH port forward of the port it names).

How long it lasts: access tokens last 1 hour and are renewed automatically. The renewal token lasts 30 days from its last use, so if you do not use the server for 30 days you must run login again. Disconnecting the app under Connected apps in the Hoot Lens dashboard ends the sign-in immediately. When a sign-in has ended, the server tells you to run npx -y @hootlens/mcp login.

Access key. In the dashboard, open Settings, AI assistant, and create a key for one project. Set it as HOOTLENS_PAT in the client's environment. When HOOTLENS_PAT is set it is used instead of the saved sign-in. A key belongs to one project and you can revoke it in the dashboard at any time. Prefer the browser sign-in on a personal machine and keys for CI or shared setups.

Check local setup

With version 1.2.0 or later, run:

npx -y @hootlens/mcp doctor --toolsets read,replay

npx -y @hootlens/mcp doctor --authenticated --toolsets read,replay --project YOUR_PROJECT_ID --json

The default checks public readiness and OAuth metadata plus local configuration. The second command explicitly sends the existing credential to /v1/access to check the selected site and grants. Neither command refreshes tokens, changes sign-in, reads recordings or calls MCP tools. A configured PAT overrides saved browser sign-in. For a custom HTTPS API, inspect the reported origin and explicitly add --trust-api https://YOUR_EXPECTED_API before the authenticated check.

Exit codes: 0 means the selected checks passed, 1 means a service or access check failed, and 2 means the options or configuration are invalid. JSON includes schemaVersion, authenticatedMetadataVerified, check codes and recovery steps. investigationVerified stays false: ask your client for a finding and a timed narrative to prove an investigation. Doctor has a ten-second deadline and bounded response bodies; its scope is the local stdio configuration, not a remote client's saved sign-in or support for interactive views.

Create a site as an authenticated agent

With version 1.1.0 or later, opt in with login --scopes read,replay,annotate,sites:create. The verified account owner must explicitly approve site creation for all sites in the browser. The permission is never included in default login scopes. Personal access tokens, anonymous demo connections, and project-pinned connections cannot create sites. Source 1.4.0 advertises create_site on normal unpinned connections before permission is granted, so assistants can discover the action. Hosted clients that support tool-level OAuth can request that permission when the tool is called. Otherwise, reconnect and approve the requested scope explicitly. Inspect tools/list on your actual connection.

Call create_site with name, exact HTTPS origins, and one stable idempotencyKey (8 to 128 printable ASCII characters, such as a UUID). Use the same key and site arguments after a timeout or network failure within 24 hours. Idempotency protection expires after 24 hours; inspect list_projects for the intended site before creating again. The API enforces the plan's available site slots atomically. New sites use balanced privacy by default (strict is optional) and require consent. The result gives a project ID and platform-specific installation instructions. Install on public pages, arrange consent, then call check_install; creation alone does not prove recording works. If the install instructions are unavailable, use get_install_snippet for the returned project ID instead of creating another site.

start_setup and check_setup provide an email-confirmed alternative when the user explicitly requests it. The hosted MCP connector requires sign-in before either tool can be called. The public REST onboarding endpoints allow an owner to begin email confirmation without an existing account, but that is a separate entry path. The local stdio launcher also needs its configured sign-in or access key. Do not use email setup to bypass the connector's authorization, and never open the owner's confirmation link on their behalf.

Install in your client

The commands below use the local server. Replace YOUR_PROJECT_ID if you want to pin one project (optional; see Project pinning). If you did not run login, add your HOOTLENS_PAT as shown in each example.

Claude Code

Local:

claude mcp add --transport stdio hootlens -- npx -y @hootlens/mcp

with an access key instead of the saved sign-in, and a pinned project:

claude mcp add --transport stdio --env HOOTLENS_PAT=hl_pat_... hootlens -- npx -y @hootlens/mcp --project YOUR_PROJECT_ID

Hosted (then run /mcp inside Claude Code to sign in):

claude mcp add --transport http hootlens "https://mcp.hootlens.com/mcp"

Add --scope project to share the entry with your team through .mcp.json, or --scope user for all your projects.

Cursor

Add to .cursor/mcp.json in a project, or ~/.cursor/mcp.json for all projects.

Local:

{

"mcpServers": { "hootlens": { "type": "stdio", "command": "npx", "args": ["-y", "@hootlens/mcp"], "env": { "HOOTLENS_PAT": "${env:HOOTLENS_PAT}" } } } }

Leave out env to use the saved sign-in from login.

Hosted:

{

"mcpServers": { "hootlens": { "url": "https://mcp.hootlens.com/mcp" } } }

VS Code

Add to .vscode/mcp.json (the top-level key is servers, not mcpServers).

Local:

{

"inputs": [ { "type": "promptString", "id": "hootlens-pat", "description": "Hoot Lens access key", "password": true } ], "servers": { "hootlens": { "type": "stdio", "command": "npx", "args": ["-y", "@hootlens/mcp"], "env": { "HOOTLENS_PAT": "${input:hootlens-pat}" } } } }

Leave out inputs and env to use the saved sign-in fr