@webeyez/mcp-server

Webeyez Model Context Protocol (MCP) Server

Expose Webeyez session replays, JavaScript errors, conversion funnels, rage clicks, and performance diagnostics directly to your AI agents and assistants (Claude, Cursor, Windsurf, ChatGPT, etc.) using the Model Context Protocol (MCP).

What is Webeyez?

Webeyez is a real-time user experience monitoring, conversion optimization, and error diagnostics platform. It helps online businesses identify and resolve conversion leaks, user friction, client-side bugs, and performance anomalies.

The Webeyez MCP Server bridges your local AI tools directly to the Webeyez diagnostics engine. It is implemented as a secure proxy client, meaning the server runs safely on Webeyez infrastructure to protect your data and proprietary logic, while the local NPM package serves as a lightweight, secure gateway.

When to Use the Webeyez MCP Server

Use this MCP server when you want your AI developer agent or assistant to:

• Debug Client-Side Bugs: Retrieve JS console logs, stack traces, and uncaught exceptions for a user session or globally.
• Diagnose Network Failures: Analyze failed HTTP/AJAX requests (4xx/5xx errors) on your web applications.
• Identify Friction & Rage Clicks: Search user sessions containing Dead Clicks, Rage Clicks, or other frustration signals.
• Analyze Funnel Drops: Diagnose why conversion rates dropped during checkout or specific funnels.
• Quantify Revenue Loss: Retrieve estimates of business impact caused by bugs and performance drop-offs.
• Inspect Session Replays: Retrieve links to actual user session replays matching specific error criteria to witness user frustration firsthand.

Installation

You do not need to install the server globally. The package can be run directly using npx:

npx -y @webeyez/mcp-server

Connection Setup

The Webeyez MCP server supports both standard local stdio connection (using our NPM package as a secure proxy) and direct web-based SSE connections.

Option 1: Claude Desktop Configuration (Local stdio Proxy)

Add the server to your claude_desktop_config.json configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "webeyez": {
      "command": "npx",
      "args": [
        "-y",
        "@webeyez/mcp-server"
      ],
      "env": {
        "WEBEYEZ_API_KEY": "your_webeyez_api_token_here"
      }
    }
  }
}

Option 2: IDE / Editor Configuration (Cursor, Windsurf, Cline)

Configure your editor to run the MCP proxy as a shell command:

• Open your editor's Settings > Features > MCP (or equivalent).
• Add a new MCP server with type command.
• Set the command to:

  npx -y @webeyez/mcp-server
  

• Define the environment variable:
  • Key: WEBEYEZ_API_KEY
  • Value: [Your personal access token/API key]

Option 3: Remote Server-Sent Events (SSE)

Web-based clients and custom applications can connect directly to the Webeyez SSE endpoint without any local installation:

• SSE Endpoint: https://api.app.webeyez.com/mcp
• Authentication: Pass your token in the x-api-key header or as a token URL query parameter.

Available Tools

The following tools are exposed by the server for AI agents to query:

1. Core AI Query Tools

• start_webeyez_query: Starts a long-running natural language query against the Webeyez diagnostics engine. Use this to ask questions about your session data, checkout friction, JS errors, or conversion drop-offs.
• check_webeyez_status: Polls the status and retrieves the final text answer/response of a query started with start_webeyez_query.
• get_organizations_list: Lists all Webeyez organizations you have access to (along with their organizationIds).
• get_organization_domains: Lists all registered domains for a specific organization.
• logout_webeyez: Safely clears connection state and credentials.

2. Direct Resource Diagnostics

• get_js_errors: Returns client-side JavaScript console errors, occurrences, and stack traces.
• get_failed_api_calls: Lists failed HTTP/network requests (AJAX/Fetch returning 4xx or 5xx).
• get_session_examples: Retrieves recorded user session replay links matching specific filters.
• get_funnel_summary: Retrieves conversion rates and drop-off summaries for configured funnels.
• get_checkout_dropoffs: Returns checkout funnel friction details.
• get_revenue_loss_estimate: Returns estimated revenue impact caused by conversion drop-offs or errors.
• list_accounts / list_sites: Helper tools to retrieve accessible accounts and sites.

Environment Variables

• WEBEYEZ_API_KEY (Required): Your personal API Key or Personal Access Token (PAT).
• WEBEYEZ_MCP_URL (Optional): Overrides the default hosted Webeyez MCP gateway endpoint (default: https://api.app.webeyez.com/mcp).

Security & Architecture

The Webeyez MCP server uses a secure hybrid model:

• Lightweight Gateway: The NPM package published is a transparent proxy. It doesn't contain any local business logic or database drivers, preventing intellectual property exposure.
• Standard stdin/stdout: The proxy listens to standard streams, ensuring 100% compatibility with all standard MCP hosts (e.g. Claude Desktop, Cursor).
• Encrypted HTTPS/SSE Tunnel: Messages are securely routed from the proxy over TLS to the hosted Webeyez endpoints where authentication and query processing take place.

License

ISC License.