> ## 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.

# querying.ai MCP 서버로 AI 에이전트 연결하기

> Claude Code, Codex 등 MCP 클라이언트에 AI 엔진 질의, 페이지 스크래핑, 프롬프트 조사, GEO 모니터 관리 도구를 제공합니다.

querying.ai MCP 서버는 API를 [Model Context Protocol](https://modelcontextprotocol.io/) 도구로 제공합니다. REST API와 같은 엔진, 대기열, 결과 형태, API 키를 쓰며, 키나 태스크를 저장하지 않습니다.

| | |
| - | - |
| 엔드포인트 | `https://mcp.querying.ai/mcp` |
| 전송 방식 | Streamable HTTP |
| 인증 | `Authorization: Bearer <API key>` |

## 클라이언트 연결

먼저 키를 `QUERYING_API_KEY` 환경 변수에 넣으세요. 키는 [API 키](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}'
```

작은따옴표를 유지하세요. 큰따옴표를 쓰면 셸이 키를 한 번 펼쳐 버리고 Claude Code가 그 값을 설정 파일에 저장합니다.

**Codex**

`~/.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**

`mcp.json` 파일을 읽는 클라이언트라면 다음과 같습니다.

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

그 밖의 Streamable HTTP 클라이언트도 모든 요청에 다음 헤더를 보내면 동작합니다.

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

Bearer 헤더가 없는 요청은 `401`을 반환합니다. 잘못된 키는 첫 도구 호출에서 도구 오류로 보고됩니다.

## 도구

태스크를 제출하는 도구는 같은 API 호출과 비용이 같습니다. 읽기 전용 도구는 무료입니다.

### 태스크와 리서치

| 도구 | 하는 일 | 크레딧 |
| - | - | - |
| `run_prompt` | 엔진에 프롬프트를 제출하고 결과를 기다립니다. | 엔진 가격 |
| `submit_prompt` | 프롬프트를 제출하고 대기 중인 태스크를 즉시 반환합니다. | 엔진 가격 |
| `get_task` | 태스크 상태와, 끝났다면 결과를 반환합니다. | 무료 |
| `scrape_page` | 웹 페이지 하나나 텍스트 PDF를 Markdown으로 읽고(`WEB_SCRAPE`) 기다립니다. | URL당 1 |
| `read_product` | 쇼핑몰 상품 페이지 하나를 읽고(`COMMERCE_PRODUCT`) 가격, 재고, 이미지, 상세 이미지, 상품 정보, 옵션을 기다립니다. | 페이지당 3 |
| `research_prompts` | 사람들이 한 주제에 대해 AI 어시스턴트에 묻는 질문을 검색 수요 순으로 찾고, `create_monitor`에 바로 쓸 수 있는 `monitorSet`을 함께 반환합니다. 미국과 한국 시장. | 11 |
| `run_product_lookup` | AI 쇼핑 엔진에 상품과 경쟁 상품 최대 5개를 묻고 결과를 기다립니다. 엔진마다 상품을 보여줬는지, 판매처, 가격, 인용 사이트와 쇼핑 질문 답변에 나온 상품을 반환합니다. 미국과 한국 시장. | 상품당 10, 쇼핑 질문당 5 |
| `get_product_lookup` | 조회 id로 Product Lookup 결과를 요약이나 전체로 반환합니다. | 무료 |

`run_prompt`와 `submit_prompt`는 `taskType`, `prompt`와 선택 항목 `country`, `idempotencyKey`, `include`, `page`(1\~10, `GOOGLE_SERP`와 `NAVER_SERP`용)를 받습니다. 엔진과 가격은 [엔진](/ko/engines/overview.md)을, 리서치 입력은 [Prompt Research](/ko/research/prompt-research.md)를 참고하세요.

`COMMERCE_SERP`는 `prompt` 대신 `site`와 `query`를 보내고, `limit`(1\~40)은 선택입니다. [Commerce Search](/ko/engines/commerce-serp.md)를 참고하세요. `read_product`는 `url`과 선택 항목 `country`, `idempotencyKey`를 받습니다. [Commerce Product](/ko/engines/commerce-product.md)를 참고하세요.

`run_product_lookup`은 `product`, `country`와 선택 항목 `competitors`, `prompts`, `engines`, `idempotencyKey`를 받습니다. 입력은 [Product Lookup](/ko/research/product-lookup.md)을 보세요. 기본 응답은 요약입니다. 상품마다 상품을 보여준 엔진, 가격 범위, 판매처와 인용 사이트 상위 10개, 엔진별 비교 행을 담고, 쇼핑 질문마다 엔진별로 보여주거나 이름을 말한 상품을 담습니다. 전체 응답의 10분의 1 정도입니다. 모든 리스팅, 인용 페이지, 태스크 id가 필요하면 `detail: "full"`을 넘기세요.

### GEO 모니터

모니터 도구는 각각 내 키로 API를 한 번 호출하므로 소유권, 키 범위, 요금제 한도가 REST와 똑같이 적용됩니다. [GEO 모니터링](/ko/monitors.md)을 참고하세요.

| 도구 | 하는 일 | 크레딧 |
| - | - | - |
| `get_monitor_capabilities` | 모니터 엔진, 태스크당 크레딧, 한도, 지표 정의. 모니터를 설정하기 전에 호출하세요. | 무료 |
| `list_monitors` | 30일 집계가 포함된 내 모니터 목록. | 무료 |
| `get_monitor` | 모니터 하나의 레거시 상세 보기. | 무료 |
| `create_monitor` | 모니터를 만들고 첫 실행을 시작합니다. 실행마다 엔진별로 프롬프트, 지점, 샘플마다 태스크를 하나씩 제출합니다. | 실행마다. [비용과 일정](/ko/monitors.md#비용과-일정) 참고 |
| `update_monitor` | 필드를 바꾸거나 `enabled`로 일시 중지·재개합니다. | 무료. 프롬프트나 엔진이 늘면 실행당 비용이 오릅니다 |
| `delete_monitor` | 모니터와 채점 기록을 삭제합니다. 되돌릴 수 없습니다. | 무료 |
| `run_monitor` | 지금 실행을 시작합니다. | 한 번 실행분의 태스크. 예약 실행과 같이 과금 |
| `get_monitor_analytics` | 언급률과 인용률, 기간 비교, 점유율, 엔진별·프롬프트별 행. | 무료 |
| `get_monitor_sources` | 인용된 도메인이나 페이지. `nextCursor`로 페이지를 넘깁니다. | 무료 |
| `get_monitor_results` | 채점된 행. `includeEvidence`가 true면 답변 텍스트와 출처를 포함합니다. | 무료 |
| `get_monitor_answer` | 답변 하나의 Markdown, 출처, 채점 맥락. | 무료 |
| `suggest_monitor_prompts` | 브랜드 정보로 프롬프트 아이디어 초안을 만듭니다. 저장하지 않습니다. | 무료. 시간당 30회, 20초에 한 번 |
| `get_monitor_alerts` | 알림 기록과 알림이 활성 상태인지 여부. | 무료 |
| `test_monitor_alert` | 테스트 알림 이메일을 한 통 보냅니다. 모니터당 5분에 3회로 제한됩니다(`429 RATE_LIMITED`). | 무료 |

## 타임아웃

`run_prompt`, `scrape_page`, `read_product`, `research_prompts`는 태스크가 끝날 때까지 폴링합니다. `timeoutSeconds`(기본 180, 최대 900)만큼 기다립니다. 태스크가 아직 실행 중이면 `taskId`와 함께 `TASK_TIMEOUT` 오류를 반환합니다. 태스크는 계속 실행되므로 그 id로 `get_task`를 호출해 결과를 가져가세요.

`run_product_lookup`도 같은 방식으로 폴링합니다. 240초 클라이언트 타임아웃 안에 끝나도록 기본 210초를 기다리고, 대부분의 조회는 2\~3분 안에 끝납니다. 조회가 아직 실행 중이면 `lookupId`와 함께 `LOOKUP_TIMEOUT` 오류를 반환합니다. 그 id로 `get_product_lookup`을 호출하세요.

클라이언트의 도구 타임아웃은 `timeoutSeconds`보다 길게 설정하세요. Codex 예시는 기본값 180초에 맞춰 `tool_timeout_sec = 240`을 씁니다. 클라이언트가 짧은 도구 호출만 허용한다면 `submit_prompt`를 쓴 뒤 `get_task`를 호출하세요.

## 오류

도구 오류는 도구 결과 안의 JSON으로 돌아옵니다.

| 코드 | 의미 |
| - | - |
| `KEY_SCOPE_DENIED` 같은 API 오류 코드 | API가 호출을 거부했습니다. 상태와 세부 정보가 포함됩니다. [오류](/ko/concepts/errors.md)를 참고하세요. |
| `VALIDATION_ERROR` | 도구 입력이 잘못되었습니다. |
| `TASK_TIMEOUT` | 태스크가 끝나기 전에 대기가 끝났습니다. `taskId`를 포함합니다. |
| `LOOKUP_TIMEOUT` | Product Lookup의 질문이 모두 끝나기 전에 대기가 끝났습니다. `lookupId`와 아직 대기 중인 엔진을 포함합니다. |
| `TASK_FAILED` | 태스크가 실패했습니다. `taskId`와 태스크 결과를 포함합니다. |

## 과금

모든 도구 호출은 키를 소유한 계정에 REST API와 같은 가격으로 과금됩니다. 키 설정도 적용되므로 키의 [엔진 범위나 일일 크레딧 한도](/ko/authentication.md#키-설정)로 에이전트가 쓸 수 있는 양을 제한할 수 있습니다. 에이전트에는 일일 한도가 있는 범위 제한 키를 따로 주세요.


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