# MCP server

kwery runs a remote [Model Context Protocol](https://modelcontextprotocol.io) server. Connect
it to Claude, Cursor, VS Code or any other MCP client and the agent can look up live prices,
offers and trust scores itself, with the same API key and credits as the REST API.

|  |  |
|  --- | --- |
| Server URL | `https://api.kwery.co/mcp` |
| Transport | Streamable HTTP |
| Authentication | Your `kwy_live_` API key in the `x-api-key` header (or `Authorization: Bearer`) |
| Registry name | `co.kwery/price-data` in the [official MCP Registry](https://registry.modelcontextprotocol.io) |


You need an API key: [sign up](https://kwery.co/signup), then create one in the dashboard, see
[Authentication](/guides/authentication). The free plan's credits work here too.

## Connect your client 

Replace `kwy_live_...` with your key, or keep the key in an environment variable as shown.

### Claude Code 

```bash
claude mcp add --transport http kwery https://api.kwery.co/mcp \
  --header "x-api-key: kwy_live_..."
```

This adds kwery to the current project. Add `--scope user` to use it in every project. Run
`claude mcp get kwery` to check the connection, and `/mcp` in a running session to load the tools.

### Claude (claude.ai and Claude Desktop) 

Add kwery as a custom connector: **Customize → Connectors → + Add → Add custom connector**.

1. Name it `kwery`, enter the server URL `https://api.kwery.co/mcp` and click **Continue**.
2. Under **Authentication**, choose **No sign-in**: kwery uses an API key, not OAuth. Claude
tags "Sign in now" as *Detected* and warns that the connector may fail without sign-in,
because kwery refuses requests without a key. The header in the next step is the answer to
that warning.
3. Under **Request headers**, click **Add header**, enter `x-api-key` as the name and your key
as the value, and keep **Required** ticked.
4. Click **Add**. The connector page then lists kwery's 7 tools; reading tools and
`submit_batch` ask for approval by default.


On Team and Enterprise plans an owner adds the connector under **Organization settings →
Connectors**, and everyone who uses it shares that one key and its credits.

### Cursor 

In `.cursor/mcp.json` (this project) or `~/.cursor/mcp.json` (all projects):

```json
{
  "mcpServers": {
    "kwery": {
      "url": "https://api.kwery.co/mcp",
      "headers": { "x-api-key": "${env:KWERY_API_KEY}" }
    }
  }
}
```

Set `KWERY_API_KEY` in your shell profile or system environment before starting Cursor.

### VS Code 

In `.vscode/mcp.json`. VS Code asks for the key the first time the server starts and stores it
securely:

```json
{
  "inputs": [
    { "type": "promptString", "id": "kwery-api-key", "description": "kwery API key", "password": true }
  ],
  "servers": {
    "kwery": {
      "type": "http",
      "url": "https://api.kwery.co/mcp",
      "headers": { "x-api-key": "${input:kwery-api-key}" }
    }
  }
}
```

### Other clients 

Any client that supports remote MCP servers over Streamable HTTP with a custom header works:
point it at `https://api.kwery.co/mcp` and send `x-api-key`. A request without a valid key gets
HTTP 401.

## Tools 

| Tool | Use it for | Cost |
|  --- | --- | --- |
| `get_product_offers` | One product on one marketplace: price, offers, trust score | The source's credit rate |
| `compare_prices` | One product on up to 5 marketplaces in one call, ranked by price | The sum of the sources that returned a result |
| `submit_batch` | Up to 1,000 identifiers on one marketplace as a background job | Estimate first with `confirm: false`, charged per result |
| `get_batch_status` | Progress of a batch job | Free |
| `get_batch_results` | Results of a finished job, 50 per page (up to 100) | Free |
| `list_sources` | Marketplaces, countries, identifier types and credit rates | Free |
| `get_account` | Plan, credit balance and credits used | Free |


Identifiers: `gtin`, `asin` (Amazon), `id` (the marketplace's own product ID) and `pzn`
(pharmacy number where the source supports it). `list_sources` says which source accepts which.

The server also offers two prompts, `price_check` and `catalog_sweep`, and the resource
`kwery://sources` with the same marketplace list as `list_sources`.

## What the agent gets back 

Each result is a short record rather than the full API response: product title, `lowest_price`,
offer count, buy box, the cheapest offers, the [trust score](/guides/trust) with its components,
`observed_at`, whether it came from cache, and the credits it used.

- **`lowest_price`** is the cheapest **new, in-stock** offer **including shipping**. Offers the
trust score flags as suspect don't count. `lowest_price_any_condition` also counts used and
open-box offers.
- **`lowest_price_shipping`** is `null` when the marketplace didn't publish shipping; the price
is then the item price alone.
- **`lowest_price_shipping_condition`** quotes the marketplace when the shipping price isn't for
every buyer, for example Amazon's free delivery "on eligible first order".
- **Trust below 0.7** means: show the result to a person before acting on it.


## Timing 

A lookup waits up to 50 seconds for a live result, which keeps it inside the 60-second default timeout
of the official MCP SDKs. Cached results come back at once.

When the product is found but its offers are still loading at 50 seconds, the agent gets what
has arrived, marked as in progress, with the job ID. When nothing has arrived yet, it gets the
job ID only. Either way the agent can finish with `get_batch_status` and `get_batch_results`.

## Credits 

MCP calls use the same credits as the API, at the per-source rates on the
[pricing page](/guides/pricing#source-weights); `list_sources` shows the current rates.

- A live lookup is charged when its job completes, including a freshly crawled "not found",
and also when the agent never fetches the final result.
- Results served from cache and lookups that fail are free.
- `submit_batch` estimates first and spends nothing until it is called with `confirm: true`;
well-behaved agents show you the estimate and ask.
- On the free plan, `compare_prices` is limited to 30 calls per minute.


## Good to know 

- **Google Shopping has no GTIN lookup.** Pass the product name as `title` together with the
GTIN (`brand` improves the match), or use Google's own product ID with key `id`. Agents
usually take the title from another marketplace's result. See
[Google Shopping](/sources/google-shopping#gtin-plus-data).
- **Default comparison for Germany:** `compare_prices` without `sources` checks Amazon, Idealo
and Google Shopping. For other countries, name the sources.
- **Batch results are kept for 3 days.**
- **AliExpress** is available in the REST API only.


## Example prompts 

- "Where is GTIN 4006381333962 cheapest in Germany right now?"
- "What does ASIN B08R57HZ4Z cost on Amazon Germany, including shipping?"
- "Price these 200 GTINs on Kaufland DE, show me the credit estimate first."
- "How many kwery credits do I have left?"