AIR MCP — API 문서
4 MCP 도구 명세 + 인증 + rate limit + 응답 schema. v0.7 ACTIVE.
1. 인증 — client API key
모든 호출에 client API key 필수 (Bearer 헤더).
Authorization: Bearer YOUR_CLIENT_API_KEY
Content-Type: application/json- 발급:
- GP 콘솔 (
tb_client.client_option.api) — 광고주별 단일 키, 만료일 별도 관리. - 격리:
- 키 → tb_client 조회 → 해당 client_seq 데이터만 반환. 다른 client 접근 시
403 Forbidden. - 발급 문의:
- /contact 또는 GP 콘솔 운영팀.
2. 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 헤더.
3. MCP 도구 4종 (v0.7 ACTIVE)
get_korean_ad_market_overview default
30일 매체별 광고비 + share + distinct_clients 통합.
POST https://air.bmp.ai/mcp
{
"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://air.bmp.ai/mcp
{
"tool": "get_media_market_share"
}get_seasonal_ad_spending_pattern
광고비 시계열. period (30d/90d/180d) × granularity (day/week).
POST https://air.bmp.ai/mcp
{
"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://air.bmp.ai/mcp
{
"tool": "get_advertiser_count_by_media",
"verbosity": "compact" | "full"
}4. 응답 메타 블록
_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)
5. 오류 코드
| 코드 | 의미 | 처리 |
|---|---|---|
401 Unauthorized | API key 누락 또는 만료 | GP 콘솔에서 키 재발급 |
403 Forbidden | 다른 client 데이터 접근 시도 (CR-09 격리) | 본인 client_seq 확인 |
404 Not Found | 존재하지 않는 tool | tool 명칭 확인 |
422 Unprocessable | 잘못된 파라미터 | schema 참조 |
429 Too Many Requests | rate limit 초과 | Retry-After 헤더 대기 또는 tier 업그레이드 |
500 Internal | 서버 오류 | 30초 후 재시도, 지속 시 문의 |