npm package: @qovva/mcp
Description: Local stdio MCP server for Qovva webhook debugging.
Latest version: 0.2.0

# @qovva/mcp

Local stdio MCP server for [Qovva](https://qovva.app) — 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](https://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:

```json
{
  "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`:

```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](https://qovva.app/docs/mcp)
- [Dashboard](https://qovva.app/dashboard)
- [Pricing](https://qovva.app/pricing)