@qovva/mcp

Local stdio MCP server for Qovva — the AI-ready webhook debugger.

Connect Cursor, Claude Desktop, Windsurf, VS Code, or any MCP-aware AI client to your live webhook capture history in seconds. Search webhooks with natural language, replay payloads, inspect anomalies, and debug integration issues — all from your AI assistant.

Quick start

1. Get an API key

Sign in at qovva.app/dashboard, open API key management, and create a key named after the client you're connecting (e.g. Cursor work).

Copy the key immediately — it is shown exactly once.

2. Add to your MCP client

Cursor / Windsurf / Continue

Add to .cursor/mcp.json, .windsurf/mcp.json, or your client's equivalent:

{
  "mcpServers": {
    "qovva": {
      "command": "npx",
      "args": ["-y", "@qovva/mcp"],
      "env": {
        "QOVVA_API_BASE_URL": "https://api.qovva.app",
        "QOVVA_API_KEY": "qw_live_..."
      }
    }
  }
}

Claude Desktop

Open Settings → Developer → Edit Config and add the same block under mcpServers.

VS Code (GitHub Copilot / MCP extension)

Add to your settings.json:

{
  "mcp": {
    "servers": {
      "qovva": {
        "command": "npx",
        "args": ["-y", "@qovva/mcp"],
        "env": {
          "QOVVA_API_BASE_URL": "https://api.qovva.app",
          "QOVVA_API_KEY": "qw_live_..."
        }
      }
    }
  }
}

3. Ask your assistant

Once connected, you can ask questions in plain English and the assistant will translate them into the right tool calls:

• "Show me all failed Stripe payments from last week"
• "What did the last POST to my endpoint send in the body?"
• "Are there any anomalies in my recent Shopify webhooks?"
• "Replay the latest checkout event to localhost:3000"
• "List all my endpoints and their webhook URLs"
• "Compare the last two invoice.paid events — did the schema change?"

Available tools

| Tool | Description | |---|---| | test_qovva_connection | Verify the API key and return your active plan metadata | | get_recent_webhooks | Fetch recently captured webhooks with optional pagination and time filters | | get_webhook_by_id | Fetch full masked detail for a single webhook by its Qovva ID | | search_webhooks | Search captured webhooks by keyword, HTTP method, endpoint, or time range — supports natural language queries that the assistant decomposes into structured filters | | list_endpoints | List all your configured catch endpoints with their webhook URLs and custom response settings | | replay_webhook | Forward a captured webhook's original payload to any URL and get the response status, body, and duration | | get_anomalies | Retrieve anomalies detected by Qovva's rule-based engine — flags missing fields, type changes, and new fields compared to the baseline for each event type | | get_failed_receipts | Start here when webhooks are failing. Lists requests that your server rejected (4xx/5xx) — shows the error code, error message, request body preview, and extraction diagnostics without needing to paste server logs | | get_receipts | Complete audit trail of ALL inbound requests (both successful and failed), filterable by source (clerk, external) | | diagnose_receipt | Deep-dive into a single receipt — shows full request headers, body preview, signature verification result, field extraction paths checked, and the error response your server returned |

Prompts

| Prompt | Description | |---|---| | debug_webhooks | A guided debugging prompt that teaches the assistant how to decompose natural language questions into multi-step webhook investigations using all available tools |

Natural language search

The search_webhooks tool is designed to work with natural language. When you ask something like "Show me all failed Stripe payments from last week", the assistant breaks it down:

• query → stripe payment_intent.failed (keywords from the question)
• method → POST (webhooks are almost always POST)
• since → ISO 8601 date for 7 days ago

This works out of the box — no special syntax required.

Anomaly detection

Qovva automatically monitors the structure of your incoming webhook payloads and flags deviations:

• Missing fields — a field that was present in the last N events has disappeared
• Type changes — a field changed from string to number (or any other type shift)
• New fields — a previously unseen field appeared in the payload

Anomalies are surfaced through the get_anomalies tool and visible in the dashboard inspector. The detection engine uses stored field baselines per event type and starts flagging after 3+ consistent samples.

Requirements

• Node.js 20 or later
• A valid Qovva API key (generated from the dashboard)

Environment variables

| Variable | Required | Description | |---|---|---| | QOVVA_API_KEY | Yes | Your Qovva MCP API key | | QOVVA_API_BASE_URL | No | Qovva API origin (default: https://api.qovva.app) |

Learn more

• Qovva documentation
• Dashboard
• Pricing