AI 어시스턴트 연동 (MCP)

AdStage 는 MCP(Model Context Protocol) 서버를 제공합니다. claude.ai·Claude Code·ChatGPT 에 커넥터로 추가하면 AI 어시스턴트가 대시보드를 열지 않고 어트리뷰션 리포트·저장 리포트·딥링크·퍼널·리텐션·이벤트 카탈로그를 조회해 분석해 줍니다.

사전 준비

AdStage 계정과, 조회할 조직의 멤버십이 있어야 합니다.

서버 URL: https://api.adstage.app/mcp (대시보드 설정 > AI 어시스턴트 연동 에서 복사할 수 있습니다)

1. 보안 모델

항목	설명
권한	읽기 전용입니다. 링크 생성·설정 변경 등 쓰기 동작은 할 수 없습니다.
조직	연결할 때 조직 하나를 선택합니다. 그 조직의 데이터만 접근되며 다른 조직은 보이지 않습니다.
인증	OAuth 2.1(PKCE). API 키를 복사해 넣는 방식이 아니라 본인 AdStage 계정으로 로그인해 승인합니다.
해제	언제든 설정 > AI 어시스턴트 연동 에서 연결을 끊을 수 있고, 조직에서 제외되면 즉시 접근이 차단됩니다.
데이터	질문에 필요한 결과가 Anthropic/OpenAI 의 대화로 전달됩니다. 회사 정책에 맞는지 확인하세요.

2. claude.ai 에서 연결하기

Customize > Connectors 로 이동합니다.
Add custom connector 를 누르고 서버 URL https://api.adstage.app/mcp 를 입력한 뒤 Add 합니다.
커넥터의 Connect 를 누르면 AdStage 로그인 화면이 열립니다. 로그인 후 공유할 조직을 고르고 승인합니다.
대화에서 + > Connectors 로 AdStage 를 켜고 물어보세요. 예: "지난주 채널별 광고비와 ROAS 비교해 줘", "이번 달 일별 설치 추이 보여 줘".

Team/Enterprise 플랜은 Organization settings > Connectors 에서 Owner 가 한 번 추가하고, 멤버는 각자 Connect 를 눌러 본인 계정으로 승인합니다.

3. Claude Code 에서 연결하기

claude mcp add --transport http adstage https://api.adstage.app/mcp

세션에서 /mcp 를 실행해 로그인하면 브라우저가 열립니다. 조직을 선택하고 승인하면 도구를 쓸 수 있습니다.

4. ChatGPT 에서 연결하기

Settings > Connectors > Advanced 에서 Developer mode 를 켭니다.
Create 를 눌러 서버 URL 을 입력하고 인증 방식 OAuth 를 선택합니다.
연결 버튼을 누르면 AdStage 로그인·조직 선택·승인 화면이 열립니다.

5. 제공 도구

도구	용도
`query_attribution_report`	광고비·노출·클릭·설치·전환·매출·ROAS 를 날짜/채널/캠페인/플랫폼 등으로 집계
`list_report_fields`	사용할 수 있는 지표·차원·필터 목록
`run_saved_report` / `list_saved_reports`	대시보드에 저장한 리포트 실행
`get_event_name_histogram` / `list_event_catalog`	수집 중인 이벤트 이름과 건수
`list_deeplinks`	딥링크·트래킹 링크 목록
`list_funnels` / `get_funnel_report`	퍼널 정의와 단계별 전환
`query_retention_report`	코호트 리텐션
`list_ad_platform_integrations`	연동된 광고 매체
`get_connection_info`	연결된 조직·통화·시간대·오늘 날짜

숫자 해석 기준: 금액은 조직 기준통화, roas_*·ctr·cvr_* 는 퍼센트(×100), conversion_value_total 은 오가닉 매출 포함, roas_total 은 유료 귀속 매출 기준입니다. 기본 날짜 프리셋은 어제까지 집계합니다(오늘은 수집 중).

6. 조직 바꾸기·연결 해제

설정 > AI 어시스턴트 연동 에서 내 연결을 해제한 뒤, AI 클라이언트에서 다시 Connect 하여 다른 조직을 선택하세요. 조직 OWNER/ADMIN 은 조직 연결 탭에서 구성원 전체의 연결을 보고 끊을 수 있습니다.

7. 문제 해결

증상	조치
"Couldn't reach the MCP server"	서버 URL 이 정확히 `https://api.adstage.app/mcp` 인지 확인
로그인 화면에서 "로그인이 필요합니다" 만 반복	대시보드에 다시 로그인한 뒤 AI 클라이언트에서 재시도. 게임팟 대시보드 계정은 AD+ 탭을 한 번 연 뒤 재시도
"다른 브라우저에서 시작된 요청"	AI 클라이언트에서 연결을 시작한 같은 브라우저에서 승인해야 합니다. 연결을 다시 시작하세요
연결 가능한 조직이 없음	해당 조직의 멤버로 초대받아야 합니다(조직 설정 > 사용자)