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

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


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

클라이언트 연결

먼저 키를 QUERYING_API_KEY 환경 변수에 넣으세요. 키는 API 키에서 발급합니다.

Claude Code
Codex
mcp.json

claude mcp add --transport http querying \
  https://mcp.querying.ai/mcp \
  --header 'Authorization: Bearer ${QUERYING_API_KEY}'

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

~/.codex/config.toml에 추가하세요.

[mcp_servers.querying]
url = "https://mcp.querying.ai/mcp"
bearer_token_env_var = "QUERYING_API_KEY"
tool_timeout_sec = 240

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

{
  "mcpServers": {
    "querying": {
      "url": "https://mcp.querying.ai/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

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

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용)를 받습니다. 엔진과 가격은 엔진을, 리서치 입력은 Prompt Research를 참고하세요. COMMERCE_SERP는 prompt 대신 site와 query를 보내고, limit(1~40)은 선택입니다. Commerce Search를 참고하세요. read_product는 url과 선택 항목 country, idempotencyKey를 받습니다. Commerce Product를 참고하세요. run_product_lookup은 product, country와 선택 항목 competitors, prompts, engines, idempotencyKey를 받습니다. 입력은 Product Lookup을 보세요. 기본 응답은 요약입니다. 상품마다 상품을 보여준 엔진, 가격 범위, 판매처와 인용 사이트 상위 10개, 엔진별 비교 행을 담고, 쇼핑 질문마다 엔진별로 보여주거나 이름을 말한 상품을 담습니다. 전체 응답의 10분의 1 정도입니다. 모든 리스팅, 인용 페이지, 태스크 id가 필요하면 detail: "full"을 넘기세요.

GEO 모니터

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

도구	하는 일	크레딧
`get_monitor_capabilities`	모니터 엔진, 태스크당 크레딧, 한도, 지표 정의. 모니터를 설정하기 전에 호출하세요.	무료
`list_monitors`	30일 집계가 포함된 내 모니터 목록.	무료
`get_monitor`	모니터 하나의 레거시 상세 보기.	무료
`create_monitor`	모니터를 만들고 첫 실행을 시작합니다. 실행마다 엔진별로 프롬프트, 지점, 샘플마다 태스크를 하나씩 제출합니다.	실행마다. 비용과 일정 참고
`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가 호출을 거부했습니다. 상태와 세부 정보가 포함됩니다. 오류를 참고하세요.
`VALIDATION_ERROR`	도구 입력이 잘못되었습니다.
`TASK_TIMEOUT`	태스크가 끝나기 전에 대기가 끝났습니다. `taskId`를 포함합니다.
`LOOKUP_TIMEOUT`	Product Lookup의 질문이 모두 끝나기 전에 대기가 끝났습니다. `lookupId`와 아직 대기 중인 엔진을 포함합니다.
`TASK_FAILED`	태스크가 실패했습니다. `taskId`와 태스크 결과를 포함합니다.

과금

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

시작하기

핵심 개념

답변 엔진

검색과 웹 데이터

요청 옵션

리서치

GEO 모니터링

계정과 데이터

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

클라이언트 연결

도구

태스크와 리서치

GEO 모니터

타임아웃

오류

과금

​클라이언트 연결

​도구

​태스크와 리서치

​GEO 모니터

​타임아웃

​오류

​과금

클라이언트 연결

도구

태스크와 리서치

GEO 모니터

타임아웃

오류

과금