# API 문서 — MCP · REST 연동 가이드 | AIR

> DEVELOPER DOCS MCP · REST API 문서 MCP REST(OpenAPI 3.1) 라이브 https://mcp.gmp.ai/air 1. 30초 요약 엔드포인트 https://mcp.gmp.ai/air 인증 Authorization: Bearer

## 핵심 요약
- AIR는 MCP(JSON-RPC)와 REST(OpenAPI 3.1) 방식을 모두 지원하는 광고 시장 데이터 API로, 단일 엔드포인트(https://mcp.gmp.ai/air)를 사용합니다.
- 모든 호출은 client API key(Bearer 인증)가 필요하며, 대행사는 키 1개로 여러 광고주 계정을 매핑해 운영할 수 있습니다.
- get_korean_ad_market_overview, get_media_market_share, get_seasonal_ad_spending_pattern, get_advertiser_count_by_media 등 4종의 MCP 도구를 제공합니다.
- 응답에는 _citation, _methodology, _metadata, _schema_org 같은 메타 블록이 포함되어 인용·출처·집계 방식을 확인할 수 있습니다.
- Free부터 Enterprise까지 티어별 월간·분당·일당 호출 제한이 다르며, 초과 시 429 오류와 Retry-After가 반환됩니다.

DEVELOPER DOCS

## MCP · REST API 문서

MCP
REST(OpenAPI 3.1)
라이브
https://mcp.gmp.ai/air

### 1. 30초 요약

엔드포인트
https://mcp.gmp.ai/air
인증
Authorization: Bearer <client_api_key>
전송
MCP: JSON-RPC 2.0 over HTTP · REST: JSON POST
도구
_citation
_methodology
_metadata
격리
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)"
}
발급
tb_client.client_option.api
도입 문의
다계정 운영
대행사는 키 1개로 여러 광고주를 운영합니다. 요청마다 대상 client 가 키에 매핑돼 해석되며, 매체별 OAuth·계정 매핑·대행 계층은 AIR 이 흡수합니다.
격리(CR-09)
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일 매체별 광고비와 점유율 비교해줘”

#### 3-2. ChatGPT — Actions / Custom GPT

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" }
    }
  }
}
비(非)코드 배달 경로
daas.gmp.ai 연결 가이드 →

### 4. MCP 도구 4종

#### get_korean_ad_market_overview default

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

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
granularity
지표 페이지
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"
}
연동 매체

### 5. 응답 구조 — 메타 블록

data
{
  "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
_methodology
data_source · aggregation · anonymization · batch_schedule · cardinality_method
_metadata
tool · tier · version · client_id (격리 검증용 echo)
_schema_org
schema.org Dataset JSON-LD — LLM 인용 friendly

### 6. Rate Limit

Tier
월간 호출
분당
일당
Free
1,000
10
100
Basic
10,000
30
500
Standard
50,000
60
2,000
Plus
200,000
120
10,000
Professional
1,000,000
500
50,000
Enterprise
∞
커스텀
커스텀
429 Too Many Requests
Retry-After
요금 페이지

### 7. 오류 코드

코드
의미
처리
401 Unauthorized
api_key_required
Bearer 헤더 확인 · GP 콘솔에서 키 재발급
403 Forbidden
다른 client 데이터 접근 시도 (CR-09 격리)
본인 client_seq 확인
404 Not Found
존재하지 않는 tool
tools/list
422 Unprocessable
잘못된 파라미터
위 도구 스펙의 허용값 확인
429 Too Many Requests
rate limit 초과
Retry-After
500 Internal
서버 오류
문의

### 8. 운영 원칙

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

### 9. 다음 단계

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

출처: https://air.gmp.ai/docs

## FAQ
**Q. API key 없이 호출하면 어떻게 되나요?**

A. api_key_required 오류가 반환되며 도구 목록조차 조회할 수 없습니다. GP 콘솔(tb_client.client_option.api)에서 client API key를 발급받아 Authorization: Bearer 헤더에 담아 호출해야 합니다.

**Q. 대행사인데 여러 광고주 계정을 하나의 키로 관리할 수 있나요?**

A. 네, 키 1개로 여러 광고주를 운영할 수 있으며 요청마다 대상 client가 키에 매핑되어 해석됩니다. 매체별 OAuth·계정 매핑·대행 계층은 AIR이 흡수해서 처리합니다.

**Q. 다른 광고주의 데이터에 접근하면 어떻게 되나요?**

A. CR-09 격리 정책에 따라 403 Forbidden 오류가 발생합니다. _metadata.client_id로 격리 검증용 echo 값을 확인할 수 있습니다.

**Q. Claude에서는 어떻게 연동하나요?**

A. Claude Desktop이나 Claude Code 설정 파일에 mcpServers 항목으로 AIR의 URL과 Authorization 헤더를 추가하면, 대화창에서 자연어로 광고 데이터를 조회할 수 있습니다.

**Q. 데이터는 어떻게 수집되고, 언제 업데이트되나요?**

A. 각 매체 공식 API를 통해 직접 수집하며 스크래핑은 사용하지 않습니다. 매일 새벽 배치(Daily 06:00 KST, D-1 기준)로 업데이트됩니다.

---
출처: https://bizspring.ai/kb/ref/web/air-gmp-ai/api-문서-mcp-rest-연동-가이드-air · 최종 갱신 2026-09-06T11:30:51.102164+00:00