지식센터 / 레퍼런스

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

자주 묻는 질문

API key 없이 호출하면 어떻게 되나요?

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

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

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

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

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

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

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

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

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

관련 문서

이 문서를 참조하는 문서 (역링크)

• AIR — 광고 캠페인 주요 매체를 하나의 API/MCP로. Claude·ChatGPT가 직접 조회하고, 리포트·자동화가 같은 소스를 씁니다.

다른 표현: Markdown · JSON · 최종 갱신 2026-09-06