AIR광고 매체 통합 데이터 · GMP.ai
Developer Docs

MCP · REST API 문서

AIR 은 같은 데이터를 MCP 와 REST(OpenAPI 3.1) 두 경로로 냅니다. 사람이 보는 화면과 에이전트가 호출하는 도구가 같은 소스를 쓴다는 뜻입니다. 아래는 연결 절차부터 응답 스키마·오류·한도까지의 전체 레퍼런스입니다.

라이브https://mcp.gmp.ai/air

1. 30초 요약

엔드포인트
https://mcp.gmp.ai/air — MCP(Streamable HTTP)와 REST 를 같은 호스트에서 제공
인증
Authorization: Bearer <client_api_key> — 광고주별 단일 키
전송
MCP: JSON-RPC 2.0 over HTTP · REST: JSON POST
도구
4종 (아래 4장) — 모든 응답에 _citation·_methodology·_metadata 메타 동봉
격리
키 → client 조회 → 해당 client 데이터만. 다른 client 접근 시 403
수집
각 매체 공식 API 직접 수집. 매일 새벽 배치(D-1). 스크래핑 없음

2. 인증 — client API key

모든 호출에 client API key 가 필요합니다. 키가 없으면 도구 목록도 반환하지 않습니다.

Authorization: Bearer YOUR_CLIENT_API_KEY
Content-Type: application/json

키 없이 호출하면

$ curl -s https://mcp.gmp.ai/air
{
  "error": "api_key_required",
  "detail": "Authorization: Bearer <client_api_key> required",
  "version": "v0.8-beta",
  "hint": "Issue client API key in GP console (tb_client.client_option.api)"
}
발급
GP 콘솔 (tb_client.client_option.api) — 광고주별 단일 키, 만료일 별도 관리. 도입 문의 시 담당 엔지니어가 함께 준비합니다.
다계정 운영
대행사는 키 1개로 여러 광고주를 운영합니다. 요청마다 대상 client 가 키에 매핑돼 해석되며, 매체별 OAuth·계정 매핑·대행 계층은 AIR 이 흡수합니다.
격리(CR-09)
키 → client 조회 → 해당 client_seq 데이터만 반환. 다른 client 접근 시 403 Forbidden. 응답의 _metadata.client_id 로 격리를 검증할 수 있습니다.
키 보관
서버 측 환경변수·시크릿 스토어에만 두십시오. 브라우저 번들·저장소에 평문으로 두면 안 됩니다.

3. 연결 가이드

에이전트·IDE·코드 어디서든 같은 엔드포인트를 씁니다. 아래 셋이 가장 많이 쓰이는 경로입니다.

3-1. Claude — MCP 커넥터

Claude Desktop / Claude Code 설정 파일에 아래를 추가하면, 대화창에서 자연어로 광고 데이터를 조회할 수 있습니다.

{
  "mcpServers": {
    "air": {
      "type": "http",
      "url": "https://mcp.gmp.ai/air",
      "headers": {
        "Authorization": "Bearer YOUR_CLIENT_API_KEY"
      }
    }
  }
}

연결 후 “지난 30일 매체별 광고비와 점유율 비교해줘” 처럼 물으면 Claude 가 도구를 골라 호출합니다.

3-2. ChatGPT — Actions / Custom GPT

OpenAPI 3.1 스키마를 Custom GPT 의 Action 으로 등록하고, 인증 방식은 API Key · Bearer 로 설정합니다. 스키마 파일은 도입 시 함께 전달드립니다.

3-3. Cursor · AI IDE / 직접 호출

MCP 를 지원하는 IDE 는 Claude 와 동일한 설정 형식을 씁니다. 서버 코드에서 직접 부를 때는 아래 JSON-RPC 를 그대로 POST 하면 됩니다.

POST https://mcp.gmp.ai/air
Authorization: Bearer YOUR_CLIENT_API_KEY
Content-Type: application/json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

도구 호출:

POST https://mcp.gmp.ai/air
Authorization: Bearer YOUR_CLIENT_API_KEY
Content-Type: application/json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_korean_ad_market_overview",
    "arguments": {
      "verbosity": "compact",
      "filter": { "media": "naver_sa" }
    }
  }
}

Google Sheets · Excel Power Query · Webhook(n8n·Make) · 이메일/Slack 리포트 같은 비(非)코드 배달 경로는 통합 데이터 콘솔에서 제공합니다 — daas.gmp.ai 연결 가이드 →

4. MCP 도구 4종

get_korean_ad_market_overview default

30일 매체별 광고비 + 점유율 + 활성 광고주 수 통합. filter.media 로 단일 매체만 볼 수 있습니다.

POST https://mcp.gmp.ai/air
Authorization: Bearer YOUR_CLIENT_API_KEY
Content-Type: application/json
{
  "tool": "get_korean_ad_market_overview",
  "verbosity": "compact" | "full",
  "filter": { "media": "naver_sa" }   // optional
}

get_media_market_share

광고비 기준 매체 점유율 (light projection: share_pct + rank). → 지표 페이지

POST https://mcp.gmp.ai/air
Authorization: Bearer YOUR_CLIENT_API_KEY
Content-Type: application/json
{
  "tool": "get_media_market_share"
}

get_seasonal_ad_spending_pattern

광고비 시계열. period(30d/90d/180d) × granularity(day/week). → 지표 페이지

POST https://mcp.gmp.ai/air
Authorization: Bearer YOUR_CLIENT_API_KEY
Content-Type: application/json
{
  "tool": "get_seasonal_ad_spending_pattern",
  "period": "30d" | "90d" | "180d",
  "granularity": "day" | "week"
}

get_advertiser_count_by_media

매체별 활성 광고주 수 (distinct_clients + rank). full 모드는 program_count 포함. → 지표 페이지

POST https://mcp.gmp.ai/air
Authorization: Bearer YOUR_CLIENT_API_KEY
Content-Type: application/json
{
  "tool": "get_advertiser_count_by_media",
  "verbosity": "compact" | "full"
}

※ 위 4종은 시장·매체 수준 집계 도구입니다. 광고주 계정의 캠페인·키워드·소재 단위 원천 데이터 연동은 연동 매체 기준으로 도입 시 별도 구성됩니다.

5. 응답 구조 — 메타 블록

모든 응답은 data 와 함께 네 개의 메타 블록을 동봉합니다. LLM 이 출처·방법론을 함께 읽고 인용할 수 있게 하기 위한 설계입니다.

{
  "data": { /* 도구별 페이로드 */ },
  "_citation": {
    "suggested_citation_ko": "비즈스프링 AIR (2026). ... https://air.gmp.ai",
    "suggested_citation_en": "Bizspring AIR (2026). ... https://air.gmp.ai",
    "license": "CC-BY 4.0",
    "data_authority": "Bizspring"
  },
  "_methodology": {
    "data_source": "각 매체 공식 API → Bizspring AIR 배치",
    "aggregation": "client 단위 집계 (CR-09 격리)",
    "anonymization": "개별 광고주 식별 정보 미포함",
    "batch_schedule": "Daily 06:00 KST (D-1)",
    "cardinality_method": "구간 내 distinct client 카운트"
  },
  "_metadata": {
    "tool": "<호출한 도구명>",
    "tier": "free | basic | standard | plus | professional | enterprise",
    "version": "v0.8-beta",
    "client_id": "<격리 검증용 echo>"
  },
  "_schema_org": { "@type": "Dataset", "...": "..." }
}
블록내용
_citation제안 인용 형식(KO/EN) · 라이선스(CC-BY 4.0) · data_authority
_methodologydata_source · aggregation · anonymization · batch_schedule · cardinality_method
_metadatatool · tier · version · client_id (격리 검증용 echo)
_schema_orgschema.org Dataset JSON-LD — LLM 인용 friendly

6. Rate Limit

Tier월간 호출분당일당
Free1,00010100
Basic10,00030500
Standard50,000602,000
Plus200,00012010,000
Professional1,000,00050050,000
Enterprise∞커스텀커스텀

초과 시 429 Too Many Requests + Retry-After 헤더. 요금은 요금 페이지 참고.

7. 오류 코드

코드의미처리
401 Unauthorizedapi_key_required — 키 누락 또는 만료Bearer 헤더 확인 · GP 콘솔에서 키 재발급
403 Forbidden다른 client 데이터 접근 시도 (CR-09 격리)본인 client_seq 확인
404 Not Found존재하지 않는 tooltools/list 로 도구명 확인
422 Unprocessable잘못된 파라미터위 도구 스펙의 허용값 확인
429 Too Many Requestsrate limit 초과Retry-After 대기 또는 tier 상향
500 Internal서버 오류30초 후 재시도, 지속 시 문의

8. 운영 원칙

수집 신뢰도
각 매체 공식 API 직접 수집. 스크래핑을 쓰지 않으며, 응답마다 신뢰등급(tier)과 커버리지를 표기합니다.
배치 주기
매일 새벽 자동 수집(D-1 기준). 매체별 상세 주기는 각 매체 페이지에 표기.
지표 정의
광고비·노출·클릭·전환의 정의를 매체 간 통일해 내보냅니다. 매체 원문 지표가 필요하면 도입 시 별도 협의.
라이선스
시장 집계 데이터는 CC-BY 4.0. 광고주 계정 데이터는 해당 광고주에게 귀속됩니다.
버전
현재 v0.8-beta. 호환성 깨는 변경은 사전 공지합니다.

9. 다음 단계

API key 발급 문의연동 매체 카탈로그요금비코드 연결 가이드 →