18 MCP 연결 (AI 에이전트용) — GEOcare 사용자 매뉴얼
핵심 요약
- MCP는 Claude, ChatGPT 등 AI 에이전트가 코딩 없이 대화만으로 GEOcare 기능을 사용하게 해주는 표준 연결 방식이다.
- 계정 메뉴의 'MCP 연결 설정'(/v3/user-mcp)에서 개인 키를 발급받아 AI 클라이언트에 등록하면 대화로 바로 사용할 수 있다.
- 조회(read) 약 28종, 실행(action) 10종, 관리자용 3종 등 약 41종의 도구를 MCP와 REST API가 동일하게 제공한다.
- 실행형 도구는 confirm:true를 지정해야 동작하는 2단계 안전장치가 적용된다.
- 먼저 list_my_sites로 접근 가능한 사이트를 확인한 뒤 site_domain을 지정해 다른 도구를 호출하는 방식으로 사용한다.
# 18 MCP 연결 (AI 에이전트용)
18 MCP 연결 (AI 에이전트용)
_Claude 등 AI/LLM 에이전트가 GEOcare를 대화로 바로 쓰게 하는 표준 연결_
개발자·연동 · 경로 /v3/user-mcp
> 📌 목적: \*\*MCP(Model Context Protocol)\*\*는 Claude · ChatGPT 같은 AI/LLM 에이전트를 위한 표준 규약입니다. 연결만 해두면 AI가 GEOcare 기능(도구)을 스스로 인식해, 사용자가 자연어로 묻고 시키면 알맞은 도구를 호출합니다. (코딩 불필요)
누구를 위한 것인가
- ✅ Claude Desktop · Claude.ai · Claude Code, ChatGPT, Manus 등 MCP 지원 AI 에이전트 사용자
- ✅ 대화만으로 GEO 데이터를 조회/실행하려는 마케터·운영자·경영자
- ※ 시스템 연동·자체 서비스 확장(개발자)은 \[19 REST API] 페이지 참조
연동 방법 (3단계)
- API 키 발급 — 계정 메뉴 → 'MCP 연결 설정'(/v3/user-mcp)에서 개인 키 발급(계정 단위).
- AI 클라이언트에 등록 — 단일 MCP 엔드포인트 URL+키를 클라이언트별 방식으로 등록(헤더 Bearer 또는 ?token=).
- 대화로 사용 — AI가 도구를 자동 인식(tools/list). 자연어로 묻고 시키면 도구를 호출해 답합니다.
엔드포인트 · 인증
| 항목 | 값 |
|---|---|
| 엔드포인트 | https://nntuztaehnywdbttrajy.supabase.co/functions/v1/geocare-user-mcp |
| 프로토콜 | MCP (JSON-RPC) — initialize · tools/list · tools/call |
| 인증 | 개인 토큰 — Authorization: Bearer <키> (또는 ?token=<키>) |
| 스코프 | 계정 단위 — 키 1개로 접근 가능한 모든 사이트 (호출마다 site\_domain 지정) |
제공 기능(도구) 카탈로그
MCP · REST API가 동일하게 제공하는 도구 세트(약 41종). 조회(read)는 바로, 실행(action)은 confirm:true로 동작. 관리자(admin) 도구는 super\_admin 전용. 라이브 최신 목록은 GET /api 또는 GET /openapi.json.
조회 (read) · 약 28종
| 도구 | 설명 |
|---|---|
| list\_my\_sites | 내 계정이 접근 가능한 사이트 목록 (다른 도구의 site\_domain 확인 — 먼저 호출 권장) |
| get\_site\_profile | 사이트 브랜드 프로파일 (브랜드명·별칭·업종·회사명·플랜) |
| get\_plan\_status | 플랜·쿼터(사용량) 상태 |
| check\_pipeline\_readiness | 분석 사전 준비상태 점검 (도메인·브랜드·경쟁사) |
| get\_geo\_scores | GEO/SEO 종합 점수 + 5대 KPI |
| get\_url\_analysis | URL별 분석 결과 (KPI·스키마·메타) |
| get\_eeat\_summary | EEAT 4축(경험·전문성·권위·신뢰) 요약 |
| get\_eeat\_pages | 페이지별 EEAT 점수 |
| get\_som\_summary | SoM(AI 점유율) 요약 — 엔진별·의도별 |
| get\_som\_queries | SoM 질문(쿼리) 목록 |
| get\_som\_runs | SoM 분석 실행 이력 |
| get\_competitors | 등록된 경쟁사 목록 |
| get\_competitor\_som | 경쟁사별 SoM 점유율 |
| get\_som\_gap | 선두(1위) 대비 격차 분석 |
| get\_som\_trends | SoM 추세(시계열) |
| get\_unmentioned\_questions | 우리가 미언급된 질문 = 개선 기회 |
| search\_som\_evidence | AI 응답 원문(근거) 검색 |
| get\_source\_share | AI 인용 점유율(인용 해자/Moat) |
| get\_citations | AI 응답이 인용한 출처 URL |
| get\_citation\_domains | 인용 도메인 카탈로그 |
| get\_jsonld\_status | JSON-LD 송출 상태 |
| get\_jsonld\_elements | 송출된 JSON-LD 요소(schema\_type별) |
| get\_reports | 정기진단 보고서 목록 |
| get\_brand\_reputation | 브랜드 평판 5대 지표 |
| get\_alerts | 알림(위기·기회·운영) 조회 |
| get\_alert\_settings | 알림 임계값 설정 조회 |
| get\_analysis\_jobs | 분석 작업(잡) 상태 |
| geo\_guide | GRAND G1 \~ G7 단계별 할 일·도구·화면 가이드 |
실행 (action · confirm 필요) · 10종
| 도구 | 설명 |
|---|---|
| start\_onestep | 원스텝(GRAND) 풀 파이프라인 시작 — 크롤→EEAT→SoM→JSON-LD→리포트 |
| start\_full\_analysis | 전체 분석 시작 |
| start\_crawl | 사이트 크롤 시작 |
| run\_eeat\_analysis | EEAT 분석 실행 |
| generate\_som\_queries | SoM 질문(쿼리) 생성 |
| add\_competitors | 경쟁사 추가 |
| start\_som\_analysis | SoM(AI 점유율) 분석 실행 |
| sync\_jsonld | JSON-LD 생성·송출(동기화) |
| update\_brand\_settings | 브랜드 설정(브랜드명·별칭·업종) 저장 |
| update\_alert\_settings | 알림 임계값 저장 |
관리자 (admin · super\_admin 전용) · 3종
| 도구 | 설명 |
|---|---|
| admin\_list\_customers | 전체 고객 목록 (super\_admin 전용) |
| admin\_find\_customer | 고객 검색 (super\_admin 전용) |
| admin\_customer\_overview | 고객 종합 현황 (super\_admin 전용) |
사용 규칙
- 계정 단위 — 먼저
list_my_sites로 사이트 확인 → 이후 호출에site_domain전달 - 실행형(action)은
confirm:true필요 (2단계 안전장치) - 키 = 계정 자격증명. 노출 시 'MCP 연결 설정'에서 즉시 폐기
자주 묻는 질문
MCP 연결을 쓰려면 개발 지식이 필요한가요?
아니요, 코딩이 필요 없습니다. API 키만 발급받아 AI 클라이언트에 등록하면 AI가 도구를 자동 인식해 자연어로 묻고 시키는 것만으로 사용할 수 있습니다.
MCP 키는 어디서 발급받나요?
계정 메뉴의 'MCP 연결 설정'(/v3/user-mcp) 화면에서 계정 단위로 개인 키를 발급받을 수 있습니다.
AI가 여러 사이트 중 어떤 것을 조회할지 어떻게 정하나요?
list_my_sites 도구를 먼저 호출해 접근 가능한 사이트 목록을 확인한 뒤, 이후 호출 시 site_domain을 지정해 전달하면 됩니다.
크롤이나 분석 실행 같은 작업도 대화로 시킬 수 있나요?
네, start_crawl, run_eeat_analysis 등 실행(action) 도구가 제공됩니다. 다만 실수 방지를 위해 confirm:true를 함께 지정해야 실제로 동작합니다.
키가 노출되면 어떻게 해야 하나요?
키는 계정 자격증명과 동일하므로 노출 시 'MCP 연결 설정'에서 즉시 폐기해야 합니다.