> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect AI agents with the querying.ai MCP server

> Give Claude Code, Codex or any MCP client tools to query AI engines, scrape pages, research prompts and manage GEO monitors.

The querying.ai MCP server exposes the API as [Model Context Protocol](https://modelcontextprotocol.io/) tools. It uses the same engines, queue, result shapes and API keys as the REST API, and it does not store your key or your tasks.

| | |
| - | - |
| Endpoint | `https://mcp.querying.ai/mcp` |
| Transport | Streamable HTTP |
| Authentication | `Authorization: Bearer <API key>` |

## Connect a client

Put your key in the `QUERYING_API_KEY` environment variable first. Get one from [API keys](https://querying.ai/dashboard/keys).

**Claude Code**

```bash theme={"theme":"css-variables"}
claude mcp add --transport http querying \
  https://mcp.querying.ai/mcp \
  --header 'Authorization: Bearer ${QUERYING_API_KEY}'
```

Keep the single quotes. With double quotes your shell expands the key once and Claude Code stores the value in its config file.

**Codex**

Add to `~/.codex/config.toml`:

```toml theme={"theme":"css-variables"}
[mcp_servers.querying]
url = "https://mcp.querying.ai/mcp"
bearer_token_env_var = "QUERYING_API_KEY"
tool_timeout_sec = 240
```

**mcp.json**

For clients that read an `mcp.json` file:

```json theme={"theme":"css-variables"}
{
  "mcpServers": {
    "querying": {
      "url": "https://mcp.querying.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

Any other Streamable HTTP client works if it sends these headers on every request:

```http theme={"theme":"css-variables"}
Authorization: Bearer <API key>
Accept: application/json, text/event-stream
Content-Type: application/json
```

A request without a bearer header returns `401`. An invalid key is reported by the first tool call, as a tool error.

## Tools

Tools that submit tasks cost what the same API call costs. Read-only tools are free.

### Tasks and research

| Tool | What it does | Credits |
| - | - | - |
| `run_prompt` | Submits a prompt to an engine and waits for the result. | The engine's price |
| `submit_prompt` | Submits a prompt and returns the queued task at once. | The engine's price |
| `get_task` | Returns a task's status, and its result when finished. | Free |
| `scrape_page` | Reads one web page or text PDF as Markdown (`WEB_SCRAPE`) and waits for it. | 1 per URL |
| `read_product` | Reads one storefront product page (`COMMERCE_PRODUCT`) and waits for its price, stock, images, description images, specs and options. | 3 per page |
| `research_prompts` | Finds the questions people ask AI assistants about a topic, ranked by search demand, with a `monitorSet` ready for `create_monitor`. US and KR markets. | 11 |
| `run_product_lookup` | Asks the AI shopping engines about a product and up to 5 competitors and waits for the result: where each engine lists them, merchants, prices, cited sites, and which of them shopper prompts surface. US and KR markets. | 10 per product, 5 per shopper prompt |
| `get_product_lookup` | Returns a product lookup by id, as a summary or in full. | Free |

`run_prompt` and `submit_prompt` take `taskType`, `prompt`, and optional `country`, `idempotencyKey`, `include` and `page` (1 to 10, for `GOOGLE_SERP` and `NAVER_SERP`). See [Engines](/engines/overview.md) for the engines and their prices, and [Prompt Research](/research/prompt-research.md) for the research inputs.

For `COMMERCE_SERP`, send `site` and `query` in place of `prompt`, with optional `limit` (1 to 40); see [Commerce Search](/engines/commerce-serp.md). `read_product` takes `url` and optional `country` and `idempotencyKey`; see [Commerce Product](/engines/commerce-product.md).

`run_product_lookup` takes `product`, `country` and optional `competitors`, `prompts`, `engines` and `idempotencyKey`; see [Product Lookup](/research/product-lookup.md). It returns a summary: for each product, the engines that list it, its price range, the top 10 merchants and cited sites, and one row per engine; for each shopper prompt, the products each engine showed or named. That is about a tenth of the full response. Pass `detail: "full"` for every listing, cited page and task id.

### GEO monitors

Each monitor tool makes one API call with your key, so ownership, key scope and plan limits apply as they do over REST. See [GEO monitoring](/monitors.md).

| Tool | What it does | Credits |
| - | - | - |
| `get_monitor_capabilities` | Monitor engines, per-task credits, limits and metric definitions. Call it before configuring a monitor. | Free |
| `list_monitors` | Your monitors with 30-day rollups. | Free |
| `get_monitor` | One monitor's legacy detail view. | Free |
| `create_monitor` | Creates a monitor and starts its first run. Each run submits one task per prompt, point and sample on each engine. | Per run; see [Cost and scheduling](/monitors.md#cost-and-scheduling) |
| `update_monitor` | Changes fields, or pauses and resumes with `enabled`. | Free; more prompts or engines raise the cost of each run |
| `delete_monitor` | Deletes a monitor and its scoring history. Cannot be undone. | Free |
| `run_monitor` | Starts a run now. | One run's tasks, charged like a scheduled run |
| `get_monitor_analytics` | Mention and citation rates, period comparison, share of voice, per-engine and per-prompt rows. | Free |
| `get_monitor_sources` | Cited domains or pages, paginated with `nextCursor`. | Free |
| `get_monitor_results` | Scored rows, with answer text and sources when `includeEvidence` is true. | Free |
| `get_monitor_answer` | One answer's Markdown, sources and scoring context. | Free |
| `suggest_monitor_prompts` | Drafts prompt ideas from brand facts. Nothing is saved. | Free; 30 calls per hour, one every 20 seconds |
| `get_monitor_alerts` | Alert history and whether the alert is armed. | Free |
| `test_monitor_alert` | Sends one test alert email. Limited to 3 per monitor per 5 minutes (`429 RATE_LIMITED`). | Free |

## Timeouts

`run_prompt`, `scrape_page`, `read_product` and `research_prompts` poll until the task finishes. They wait `timeoutSeconds` (default 180, maximum 900). If the task is still running, the tool returns a `TASK_TIMEOUT` error with the `taskId`. The task keeps running; call `get_task` with that id to collect it.

`run_product_lookup` polls the lookup the same way. It waits 210 seconds by default so the call ends inside a 240-second client timeout, and most lookups finish in 2 to 3 minutes. If the lookup is still running, the tool returns a `LOOKUP_TIMEOUT` error with the `lookupId`; call `get_product_lookup` with it.

Set your client's tool timeout longer than `timeoutSeconds`. The Codex example uses `tool_timeout_sec = 240` for the 180-second default. If your client allows only short tool calls, use `submit_prompt` and then `get_task`.

## Errors

Tool errors come back as JSON in the tool result:

| Code | Meaning |
| - | - |
| API error codes such as `KEY_SCOPE_DENIED` | The API rejected the call; the status and details are included. See [Errors](/concepts/errors.md). |
| `VALIDATION_ERROR` | The tool input was invalid. |
| `TASK_TIMEOUT` | The wait ended before the task finished. Includes `taskId`. |
| `LOOKUP_TIMEOUT` | The wait ended before every ask of the product lookup finished. Includes `lookupId` and the engines still pending. |
| `TASK_FAILED` | The task failed. Includes `taskId` and the task result. |

## Billing

Every tool call is billed to the account that owns the key, at the same prices as the REST API. Key settings apply: an [engine scope or daily credit limit](/authentication.md#key-settings) on the key limits what the agent can spend. Give an agent its own scoped key with a daily limit.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.