{
  "id": "da95f3bd-7653-48b6-9b64-41f8d5bbe6b8",
  "slug": "ref/web/air-gmp-ai/api-문서-mcp-rest-연동-가이드-air",
  "doc_type": "ref",
  "title": "API 문서 — MCP · REST 연동 가이드 | AIR",
  "title_en": null,
  "one_liner": "DEVELOPER DOCS MCP · REST API 문서 MCP REST(OpenAPI 3.1) 라이브 https://mcp.gmp.ai/air 1. 30초 요약 엔드포인트 https://mcp.gmp.ai/air 인증 Authorization: Bearer",
  "summary_bullets": [
    "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가 반환됩니다."
  ],
  "body_md": "DEVELOPER DOCS\n\n## MCP · REST API 문서\n\nMCP\nREST(OpenAPI 3.1)\n라이브\nhttps://mcp.gmp.ai/air\n\n### 1. 30초 요약\n\n엔드포인트\nhttps://mcp.gmp.ai/air\n인증\nAuthorization: Bearer <client_api_key>\n전송\nMCP: JSON-RPC 2.0 over HTTP · REST: JSON POST\n도구\n_citation\n_methodology\n_metadata\n격리\n403\n수집\n각 매체 공식 API 직접 수집. 매일 새벽 배치(D-1). 스크래핑 없음\n\n### 2. 인증 — client API key\n\n모든 호출에 client API key 가 필요합니다. 키가 없으면 도구 목록도 반환하지 않습니다.\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n\n#### 키 없이 호출하면\n\n$ curl -s https://mcp.gmp.ai/air\n{\n  \"error\": \"api_key_required\",\n  \"detail\": \"Authorization: Bearer <client_api_key> required\",\n  \"version\": \"v0.8-beta\",\n  \"hint\": \"Issue client API key in GP console (tb_client.client_option.api)\"\n}\n발급\ntb_client.client_option.api\n도입 문의\n다계정 운영\n대행사는 키 1개로 여러 광고주를 운영합니다. 요청마다 대상 client 가 키에 매핑돼 해석되며, 매체별 OAuth·계정 매핑·대행 계층은 AIR 이 흡수합니다.\n격리(CR-09)\n403 Forbidden\n_metadata.client_id\n키 보관\n서버 측 환경변수·시크릿 스토어에만 두십시오. 브라우저 번들·저장소에 평문으로 두면 안 됩니다.\n\n### 3. 연결 가이드\n\n에이전트·IDE·코드 어디서든 같은 엔드포인트를 씁니다. 아래 셋이 가장 많이 쓰이는 경로입니다.\n\n#### 3-1. Claude — MCP 커넥터\n\nClaude Desktop / Claude Code 설정 파일에 아래를 추가하면, 대화창에서 자연어로 광고 데이터를 조회할 수 있습니다.\n{\n  \"mcpServers\": {\n    \"air\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.gmp.ai/air\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_CLIENT_API_KEY\"\n      }\n    }\n  }\n}\n“지난 30일 매체별 광고비와 점유율 비교해줘”\n\n#### 3-2. ChatGPT — Actions / Custom GPT\n\nAPI Key · Bearer\n\n#### 3-3. Cursor · AI IDE / 직접 호출\n\nMCP 를 지원하는 IDE 는 Claude 와 동일한 설정 형식을 씁니다. 서버 코드에서 직접 부를 때는 아래 JSON-RPC 를 그대로 POST 하면 됩니다.\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/list\"\n}\n도구 호출:\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_korean_ad_market_overview\",\n    \"arguments\": {\n      \"verbosity\": \"compact\",\n      \"filter\": { \"media\": \"naver_sa\" }\n    }\n  }\n}\n비(非)코드 배달 경로\ndaas.gmp.ai 연결 가이드 →\n\n### 4. MCP 도구 4종\n\n#### get_korean_ad_market_overview default\n\nfilter.media\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"tool\": \"get_korean_ad_market_overview\",\n  \"verbosity\": \"compact\" | \"full\",\n  \"filter\": { \"media\": \"naver_sa\" }   // optional\n}\n\n#### get_media_market_share\n\nshare_pct\nrank\n지표 페이지\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"tool\": \"get_media_market_share\"\n}\n\n#### get_seasonal_ad_spending_pattern\n\nperiod\ngranularity\n지표 페이지\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"tool\": \"get_seasonal_ad_spending_pattern\",\n  \"period\": \"30d\" | \"90d\" | \"180d\",\n  \"granularity\": \"day\" | \"week\"\n}\n\n#### get_advertiser_count_by_media\n\ndistinct_clients\nrank\nfull\nprogram_count\n지표 페이지\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"tool\": \"get_advertiser_count_by_media\",\n  \"verbosity\": \"compact\" | \"full\"\n}\n연동 매체\n\n### 5. 응답 구조 — 메타 블록\n\ndata\n{\n  \"data\": { /* 도구별 페이로드 */ },\n  \"_citation\": {\n    \"suggested_citation_ko\": \"비즈스프링 AIR (2026). ... https://air.gmp.ai\",\n    \"suggested_citation_en\": \"Bizspring AIR (2026). ... https://air.gmp.ai\",\n    \"license\": \"CC-BY 4.0\",\n    \"data_authority\": \"Bizspring\"\n  },\n  \"_methodology\": {\n    \"data_source\": \"각 매체 공식 API → Bizspring AIR 배치\",\n    \"aggregation\": \"client 단위 집계 (CR-09 격리)\",\n    \"anonymization\": \"개별 광고주 식별 정보 미포함\",\n    \"batch_schedule\": \"Daily 06:00 KST (D-1)\",\n    \"cardinality_method\": \"구간 내 distinct client 카운트\"\n  },\n  \"_metadata\": {\n    \"tool\": \"<호출한 도구명>\",\n    \"tier\": \"free | basic | standard | plus | professional | enterprise\",\n    \"version\": \"v0.8-beta\",\n    \"client_id\": \"<격리 검증용 echo>\"\n  },\n  \"_schema_org\": { \"@type\": \"Dataset\", \"...\": \"...\" }\n}\n블록\n내용\n_citation\n제안 인용 형식(KO/EN) · 라이선스(CC-BY 4.0) · data_authority\n_methodology\ndata_source · aggregation · anonymization · batch_schedule · cardinality_method\n_metadata\ntool · tier · version · client_id (격리 검증용 echo)\n_schema_org\nschema.org Dataset JSON-LD — LLM 인용 friendly\n\n### 6. Rate Limit\n\nTier\n월간 호출\n분당\n일당\nFree\n1,000\n10\n100\nBasic\n10,000\n30\n500\nStandard\n50,000\n60\n2,000\nPlus\n200,000\n120\n10,000\nProfessional\n1,000,000\n500\n50,000\nEnterprise\n∞\n커스텀\n커스텀\n429 Too Many Requests\nRetry-After\n요금 페이지\n\n### 7. 오류 코드\n\n코드\n의미\n처리\n401 Unauthorized\napi_key_required\nBearer 헤더 확인 · GP 콘솔에서 키 재발급\n403 Forbidden\n다른 client 데이터 접근 시도 (CR-09 격리)\n본인 client_seq 확인\n404 Not Found\n존재하지 않는 tool\ntools/list\n422 Unprocessable\n잘못된 파라미터\n위 도구 스펙의 허용값 확인\n429 Too Many Requests\nrate limit 초과\nRetry-After\n500 Internal\n서버 오류\n문의\n\n### 8. 운영 원칙\n\n수집 신뢰도\n각 매체 공식 API 직접 수집. 스크래핑을 쓰지 않으며, 응답마다 신뢰등급(tier)과 커버리지를 표기합니다.\n배치 주기\n매체 페이지\n지표 정의\n광고비·노출·클릭·전환의 정의를 매체 간 통일해 내보냅니다. 매체 원문 지표가 필요하면 도입 시 별도 협의.\n라이선스\n시장 집계 데이터는 CC-BY 4.0. 광고주 계정 데이터는 해당 광고주에게 귀속됩니다.\n버전\nv0.8-beta\n\n### 9. 다음 단계\n\nAPI key 발급 문의\n연동 매체 카탈로그\n요금\n비코드 연결 가이드 →\n\n출처: https://air.gmp.ai/docs",
  "related_slugs": [],
  "faq": [
    {
      "a": "api_key_required 오류가 반환되며 도구 목록조차 조회할 수 없습니다. GP 콘솔(tb_client.client_option.api)에서 client API key를 발급받아 Authorization: Bearer 헤더에 담아 호출해야 합니다.",
      "q": "API key 없이 호출하면 어떻게 되나요?"
    },
    {
      "a": "네, 키 1개로 여러 광고주를 운영할 수 있으며 요청마다 대상 client가 키에 매핑되어 해석됩니다. 매체별 OAuth·계정 매핑·대행 계층은 AIR이 흡수해서 처리합니다.",
      "q": "대행사인데 여러 광고주 계정을 하나의 키로 관리할 수 있나요?"
    },
    {
      "a": "CR-09 격리 정책에 따라 403 Forbidden 오류가 발생합니다. _metadata.client_id로 격리 검증용 echo 값을 확인할 수 있습니다.",
      "q": "다른 광고주의 데이터에 접근하면 어떻게 되나요?"
    },
    {
      "a": "Claude Desktop이나 Claude Code 설정 파일에 mcpServers 항목으로 AIR의 URL과 Authorization 헤더를 추가하면, 대화창에서 자연어로 광고 데이터를 조회할 수 있습니다.",
      "q": "Claude에서는 어떻게 연동하나요?"
    },
    {
      "a": "각 매체 공식 API를 통해 직접 수집하며 스크래핑은 사용하지 않습니다. 매일 새벽 배치(Daily 06:00 KST, D-1 기준)로 업데이트됩니다.",
      "q": "데이터는 어떻게 수집되고, 언제 업데이트되나요?"
    }
  ],
  "jsonld": null,
  "keywords": [],
  "source_id": "https://air.gmp.ai/docs",
  "video_url": null,
  "duration_sec": null,
  "thumbnail_url": null,
  "image_url": null,
  "caption": null,
  "solution_slug": null,
  "captured_at": null,
  "width": null,
  "height": null,
  "created_at": "2026-09-06T11:30:51.102164+00:00",
  "updated_at": "2026-09-06T11:30:51.102164+00:00",
  "visibility": "public",
  "source_stage": "1",
  "anonymized": true,
  "source_key": "web-air",
  "origin": "ingest",
  "locked": false,
  "locked_by": null,
  "locked_at": null,
  "gate_state": {
    "g1": {
      "hits": [],
      "pass": true
    },
    "g2": {
      "pass": true,
      "total": 37,
      "issues": [
        "숫자·규격 같은 검증 가능한 구체가 부족합니다",
        "다른 문서와 겹치는 말이 대부분입니다"
      ],
      "applies": true
    },
    "g3": {
      "pass": true,
      "required": false
    },
    "stage": "1",
    "decided_at": "2026-09-06T11:49:12.429Z"
  },
  "raw_id": "d5e92e50-1120-4e49-9628-6864a347bafa",
  "search_text": "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  DEVELOPER DOCS\n\n## MCP · REST API 문서\n\nMCP\nREST(OpenAPI 3.1)\n라이브\nhttps://mcp.gmp.ai/air\n\n### 1. 30초 요약\n\n엔드포인트\nhttps://mcp.gmp.ai/air\n인증\nAuthorization: Bearer <client_api_key>\n전송\nMCP: JSON-RPC 2.0 over HTTP · REST: JSON POST\n도구\n_citation\n_methodology\n_metadata\n격리\n403\n수집\n각 매체 공식 API 직접 수집. 매일 새벽 배치(D-1). 스크래핑 없음\n\n### 2. 인증 — client API key\n\n모든 호출에 client API key 가 필요합니다. 키가 없으면 도구 목록도 반환하지 않습니다.\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n\n#### 키 없이 호출하면\n\n$ curl -s https://mcp.gmp.ai/air\n{\n  \"error\": \"api_key_required\",\n  \"detail\": \"Authorization: Bearer <client_api_key> required\",\n  \"version\": \"v0.8-beta\",\n  \"hint\": \"Issue client API key in GP console (tb_client.client_option.api)\"\n}\n발급\ntb_client.client_option.api\n도입 문의\n다계정 운영\n대행사는 키 1개로 여러 광고주를 운영합니다. 요청마다 대상 client 가 키에 매핑돼 해석되며, 매체별 OAuth·계정 매핑·대행 계층은 AIR 이 흡수합니다.\n격리(CR-09)\n403 Forbidden\n_metadata.client_id\n키 보관\n서버 측 환경변수·시크릿 스토어에만 두십시오. 브라우저 번들·저장소에 평문으로 두면 안 됩니다.\n\n### 3. 연결 가이드\n\n에이전트·IDE·코드 어디서든 같은 엔드포인트를 씁니다. 아래 셋이 가장 많이 쓰이는 경로입니다.\n\n#### 3-1. Claude — MCP 커넥터\n\nClaude Desktop / Claude Code 설정 파일에 아래를 추가하면, 대화창에서 자연어로 광고 데이터를 조회할 수 있습니다.\n{\n  \"mcpServers\": {\n    \"air\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.gmp.ai/air\",\n      \"headers\": {\n        \"Authorization\": \"Bearer YOUR_CLIENT_API_KEY\"\n      }\n    }\n  }\n}\n“지난 30일 매체별 광고비와 점유율 비교해줘”\n\n#### 3-2. ChatGPT — Actions / Custom GPT\n\nAPI Key · Bearer\n\n#### 3-3. Cursor · AI IDE / 직접 호출\n\nMCP 를 지원하는 IDE 는 Claude 와 동일한 설정 형식을 씁니다. 서버 코드에서 직접 부를 때는 아래 JSON-RPC 를 그대로 POST 하면 됩니다.\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"tools/list\"\n}\n도구 호출:\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2,\n  \"method\": \"tools/call\",\n  \"params\": {\n    \"name\": \"get_korean_ad_market_overview\",\n    \"arguments\": {\n      \"verbosity\": \"compact\",\n      \"filter\": { \"media\": \"naver_sa\" }\n    }\n  }\n}\n비(非)코드 배달 경로\ndaas.gmp.ai 연결 가이드 →\n\n### 4. MCP 도구 4종\n\n#### get_korean_ad_market_overview default\n\nfilter.media\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"tool\": \"get_korean_ad_market_overview\",\n  \"verbosity\": \"compact\" | \"full\",\n  \"filter\": { \"media\": \"naver_sa\" }   // optional\n}\n\n#### get_media_market_share\n\nshare_pct\nrank\n지표 페이지\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"tool\": \"get_media_market_share\"\n}\n\n#### get_seasonal_ad_spending_pattern\n\nperiod\ngranularity\n지표 페이지\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"tool\": \"get_seasonal_ad_spending_pattern\",\n  \"period\": \"30d\" | \"90d\" | \"180d\",\n  \"granularity\": \"day\" | \"week\"\n}\n\n#### get_advertiser_count_by_media\n\ndistinct_clients\nrank\nfull\nprogram_count\n지표 페이지\nPOST https://mcp.gmp.ai/air\nAuthorization: Bearer YOUR_CLIENT_API_KEY\nContent-Type: application/json\n{\n  \"tool\": \"get_advertiser_count_by_media\",\n  \"verbosity\": \"compact\" | \"full\"\n}\n연동 매체\n\n### 5. 응답 구조 — 메타 블록\n\ndata\n{\n  \"data\": { /* 도구별 페이로드 */ },\n  \"_citation\": {\n    \"suggested_citation_ko\": \"비즈스프링 AIR (2026). ... https://air.gmp.ai\",\n    \"suggested_citation_en\": \"Bizspring AIR (2026). ... https://air.gmp.ai\",\n    \"license\": \"CC-BY 4.0\",\n    \"data_authority\": \"Bizspring\"\n  },\n  \"_methodology\": {\n    \"data_source\": \"각 매체 공식 API → Bizspring AIR 배치\",\n    \"aggregation\": \"client 단위 집계 (CR-09 격리)\",\n    \"anonymization\": \"개별 광고주 식별 정보 미포함\",\n    \"batch_schedule\": \"Daily 06:00 KST (D-1)\",\n    \"cardinality_method\": \"구간 내 distinct client 카운트\"\n  },\n  \"_metadata\": {\n    \"tool\": \"<호출한 도구명>\",\n    \"tier\": \"free | basic | standard | plus | professional | enterprise\",\n    \"version\": \"v0.8-beta\",\n    \"client_id\": \"<격리 검증용 echo>\"\n  },\n  \"_schema_org\": { \"@type\": \"Dataset\", \"...\": \"...\" }\n}\n블록\n내용\n_citation\n제안 인용 형식(KO/EN) · 라이선스(CC-BY 4.0) · data_authority\n_methodology\ndata_source · aggregation · anonymization · batch_schedule · cardinality_method\n_metadata\ntool · tier · version · client_id (격리 검증용 echo)\n_schema_org\nschema.org Dataset JSON-LD — LLM 인용 friendly\n\n### 6. Rate Limit\n\nTier\n월간 호출\n분당\n일당\nFree\n1,000\n10\n100\nBasic\n10,000\n30\n500\nStandard\n50,000\n60\n2,000\nPlus\n200,000\n120\n10,000\nProfessional\n1,000,000\n500\n50,000\nEnterprise\n∞\n커스텀\n커스텀\n429 Too Many Requests\nRetry-After\n요금 페이지\n\n### 7. 오류 코드\n\n코드\n의미\n처리\n401 Unauthorized\napi_key_required\nBearer 헤더 확인 · GP 콘솔에서 키 재발급\n403 Forbidden\n다른 client 데이터 접근 시도 (CR-09 격리)\n본인 client_seq 확인\n404 Not Found\n존재하지 않는 tool\ntools/list\n422 Unprocessable\n잘못된 파라미터\n위 도구 스펙의 허용값 확인\n429 Too Many Requests\nrate limit 초과\nRetry-After\n500 Internal\n서버 오류\n문의\n\n### 8. 운영 원칙\n\n수집 신뢰도\n각 매체 공식 API 직접 수집. 스크래핑을 쓰지 않으며, 응답마다 신뢰등급(tier)과 커버리지를 표기합니다.\n배치 주기\n매체 페이지\n지표 정의\n광고비·노출·클릭·전환의 정의를 매체 간 통일해 내보냅니다. 매체 원문 지표가 필요하면 도입 시 별도 협의.\n라이선스\n시장 집계 데이터는 CC-BY 4.0. 광고주 계정 데이터는 해당 광고주에게 귀속됩니다.\n버전\nv0.8-beta\n\n### 9. 다음 단계\n\nAPI key 발급 문의\n연동 매체 카탈로그\n요금\n비코드 연결 가이드 →\n\n출처: https://air.gmp.ai/docs",
  "embedding": null,
  "embedded_at": null,
  "embedding_hash": null,
  "map_x": null,
  "map_y": null,
  "backlinks": [
    "screenshot/air-gmp-ai"
  ],
  "html_url": "https://bizspring.ai/kb/ref/web/air-gmp-ai/api-문서-mcp-rest-연동-가이드-air",
  "markdown_url": "https://bizspring.ai/kb/ref/web/air-gmp-ai/api-문서-mcp-rest-연동-가이드-air.md"
}