---
name: qomvia
description: "Monitor a user's own sites in Qomvia: site reports and fixes, rescans, AI Monitor phrases and runs, competitors, and product visibility. Use when an account owner asks an assistant to manage or understand these monitors."
license: CC-BY-4.0
metadata:
  homepage: "https://qomvia.com/"
  mcp: "https://qomvia.com/api/mcp/account"
  docs: "https://qomvia.com/mcp"
---

# Qomvia account MCP

Use this skill to manage a user's own Qomvia sites through the authenticated account MCP server.

## Setup

1. In an OAuth-capable MCP client, connect to Qomvia and sign in on the consent screen.
2. For scripts or clients without OAuth, create an API key in Dashboard → API & MCP → API keys.
3. Choose Read only, Read and edit, or Full (can spend credits); restrict access to verified owned sites when possible.
4. If using a key, store it as `QOMVIA_API_KEY` in the MCP client's secret store. Send `Authorization: Bearer qvk_live_…`. Never put a key in a URL, chat, or log.

OAuth uses public-client authorization code flow with PKCE S256. Discover endpoints at `https://qomvia.com/.well-known/oauth-authorization-server`; client secrets and Client ID Metadata Documents (CIMD) are not supported.

Claude Code:

```sh
claude mcp add --transport http qomvia https://qomvia.com/api/mcp/account --header "Authorization: Bearer $QOMVIA_API_KEY"
```

Claude Desktop and Cursor:

```json
{
  "mcpServers": {
    "qomvia": {
      "type": "http",
      "url": "https://qomvia.com/api/mcp/account",
      "headers": { "Authorization": "Bearer ${QOMVIA_API_KEY}" }
    }
  }
}
```

ChatGPT and Claude.ai: add `https://qomvia.com/api/mcp/account` as a custom connector and sign in with Qomvia.

## Workflow

1. Call `whoami`, then `list_sites`; use only a site listed for this account.
2. Pick a task below and read the matching reference before changing settings or starting a run.
3. Call the relevant `estimate_*` tool before a credit-using run when one is available. Show the credit cost, then pass that amount as `max_credits`.
4. Use an 8–100 character `idempotency_key` containing only letters, digits, `_` or `-`. Reuse the same key when retrying a request.
5. Poll `get_run` with `wait_seconds: 25` until the run is terminal. Do not start another run while one is queued.
6. Relay any credit shortfall notice; pass `allow_partial: true` only when the user wants the covered questions run.

`run_head_to_head` checks its estimate and `max_credits` before scheduling; there is no separate head-to-head estimate tool.

## Explain results

- Cite the run date. Separate mention rate, citation rate, average rank, and share of voice.
- A phrase has a rank only when its answer mentions the site.
- Present recommendations as opportunities, not guaranteed outcomes.
- Do not scan a site the user does not own.

## Errors

| Code | What to tell the user |
| --- | --- |
| `plan_required` | Name the required plan and link to [Billing](https://qomvia.com/dashboard/billing). |
| `unverified` | Verify the site's ownership before writing or starting a run. |
| `insufficient_credits` | Show the required and available credits; link to Billing. |
| `budget_exceeded` | Show the estimate and ask for a higher `max_credits` ceiling. |
| `rate_limited` | Wait for the supplied `retry_after` before retrying. |
| `cooldown` | Wait for the supplied `retry_after` before rescanning. |
| `scope_required` | Name the missing scope and ask the owner to grant it to the client or key. |
| `invalid_scope` | The request exceeds the existing grant; unknown scopes are ignored. |
| `invalid_grant` | The code or refresh token is expired, already used, or belongs to another client. Ask the owner to reconnect. |
| `invalid_target` | Use the account MCP resource URI returned by protected-resource metadata. |
| `invalid_client` | Check the registered public client ID. |

## References

- [Site monitor](references/site-monitor.md)
- [AI Monitor](references/ai-monitor.md)
- [Competitors](references/competitors.md)
- [Products](references/products.md)
- [Tool reference](references/tools.md)