AI MCP 연동 가이드

Claude Desktop, VS Code GitHub Copilot 등 AI 어시스턴트에서 자연어로 단축 URL 생성·통계·캠페인 관리를 직접 제어합니다.

베타MCP 서버 주소
MCP 서버 엔드포인트: https://mcp.fingerpush.link/mcp/sse
Service API KEY가 필요합니다. 콘솔 > 개발자 > API 키 관리에서 발급하세요.

MCP란?

MCP (Model Context Protocol)는 Anthropic이 개발한 오픈 표준으로, AI 어시스턴트가 외부 서비스의 도구(Tool)를 직접 호출할 수 있게 해주는 프로토콜입니다.

FINGERPUSH.LINK MCP 서버를 연결하면 Claude, GitHub Copilot 등에서 추가 코딩 없이 자연어 명령만으로 다음과 같은 작업이 가능합니다:

  • "이 URL 단축해줘" → 단축 URL 즉시 생성
  • "지난주 캠페인 클릭 수 분석해줘" → 통계 조회 후 분석 결과 제공
  • "오늘 가장 인기 있는 링크 3개 알려줘" → URL 목록 조회 후 정렬 제시
  • "신규 여름 세일 캠페인 만들어줘" → 캠페인 파라미터 확인 후 자동 생성
동작 흐름
사용자 → AI (Claude/Copilot)
         → MCP 서버 (mcp-dot-fingerpushai.appspot.com)
              → service-app REST API (X-API-KEY 인증)
         ← 결과 반환
AI → 사용자 (자연어 응답 생성)

시작하기

1단계: Service API KEY 발급

콘솔 > 개발자 > API 키 관리에서 Service API KEY를 발급받습니다. 이미 발급된 키가 있다면 해당 키를 사용하세요.

보안API KEY 관리
API KEY는 조직의 모든 데이터에 접근할 수 있습니다. 설정 파일에 직접 입력하는 경우 Git 저장소에 커밋되지 않도록 주의하세요.

2단계: Claude.ai 웹에서 연결 (가장 간단)

플랜Pro 이상 전용
Claude.ai 웹의 MCP 커넥터 기능은 Claude Pro, Team, Enterprise 플랜에서만 사용 가능합니다.

설정 파일 없이 브라우저에서 바로 MCP 서버를 연결할 수 있습니다. 가장 빠르게 시작하는 방법입니다.

  1. claude.ai → 좌측 하단 이름 클릭 → 설정
  2. 커넥터 탭 클릭
  3. 통합 추가 버튼 클릭 후 아래 URL 입력:
    https://mcp.fingerpush.link/mcp/sse
  4. 팝업 창에서 조직 API 키를 입력하고 인증하기 클릭
  5. 연결 완료 후 채팅창에서 바로 단축 URL 도구 사용 가능

3단계: Claude Desktop 설정

Claude Desktop 앱의 설정 파일 (claude_desktop_config.json)을 열고 MCP 서버 URL을 추가합니다.

파일 위치: %APPDATA%\Claude\claude_desktop_config.json (Windows) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

방법 1 — OAuth 인증 (권장): URL만 입력하면 재시작 후 API 키 입력 화면이 자동으로 표시됩니다.

claude_desktop_config.json
{
  "mcpServers": {
    "fingerpushlink": {
      "url": "https://mcp.fingerpush.link/mcp/sse"
    }
  }
}

방법 2 — API 키 직접 입력: 콘솔 > API 키 관리에서 발급한 Service API KEY를 직접 입력합니다.

claude_desktop_config.json
{
  "mcpServers": {
    "fingerpushlink": {
      "url": "https://mcp.fingerpush.link/mcp/sse",
      "headers": {
        "X-API-KEY": "콘솔_API_키_관리에서_발급한_X-API-KEY_값"
      }
    }
  }
}

설정 후 Claude Desktop을 완전히 종료하고 재시작합니다. 재시작 후 채팅 창 하단에 🔧 도구 아이콘이 나타나면 연결 성공입니다.

4단계: VS Code GitHub Copilot 설정

프로젝트 루트에 .vscode/mcp.json 파일을 생성합니다. URL만 입력하면 VS Code가 자동으로 OAuth 인증 팝업을 표시하고 화면에서 API 키를 입력할 수 있습니다.

.vscode/mcp.json
{
  "servers": {
    "fingerpushlink": {
      "type": "http",
      "url": "https://mcp.fingerpush.link/mcp/sse"
    }
  }
}

5단계: 연결 확인

AI에게 아래 명령을 입력해 보세요. 대시보드 요약이 표시되면 정상 연결된 것입니다.

테스트 명령
fingerpushlink 대시보드 요약 보여줘

지원 도구(Tool) 목록

현재 29개의 도구가 제공됩니다. AI가 사용자 요청에 따라 적절한 도구를 자동 선택합니다.

도구 이름설명필수 파라미터
URL 관리 (9개)
create_short_url 단축 URL 생성 (딥링크·UTM·OG태그·앱 연동 지원) url
bulk_create_urls 단축 URL 대량 생성 (배열) urls
list_urls URL 목록 조회 (페이징/검색) 없음
get_url_stats 특정 URL의 클릭 통계 조회 id
get_url_qr URL QR 코드(Base64 PNG) 조회 id
get_url_install_stats URL 경유 앱 설치 통계 (기간별) id
update_url 원본 URL, 제목, 만료일, UTM·딥링크·OG태그 등 수정 id
delete_url 단축 URL 삭제 id
get_url 단축 URL 단건 상세 조회 (딥링크·UTM·OG태그 설정값 확인) id
캠페인 (7개)
create_campaign 캠페인 생성 (딥링크·UTM·OG태그·앱 연동 지원) name, originalUrl, alias, expiresAt
list_campaigns 캠페인 목록 조회 (페이징/검색) 없음
get_campaign_stats 캠페인 클릭·기기·지역 통계 조회 id
update_campaign 캠페인 이름, 원본 URL, 만료일, UTM·딥링크·OG태그 등 수정 id
delete_campaign 캠페인 삭제 id
get_campaign 캠페인 단건 상세 조회 (딥링크·UTM·OG태그 설정값 확인) id
get_campaign_install_stats 캠페인 경유 앱 설치 통계 (기간별) id
앱 · 통계 (7개)
list_mobile_apps 모바일/웹 앱 목록 및 요약 통계 없음
get_mau_stats 월간 활성 사용자(MAU) 통계 조회 year
get_app_install_stats 앱별 설치 수 통계 (기간별) appId
get_funnel_stats 클릭→설치→재참여 퍼널 통계 조회 appId
get_session_journey 사용자 세션 여정 분석 (URL/캠페인 기준) 없음
get_dashboard_summary 대시보드 요약 (전체 URL 수, 클릭 수 등) 없음
get_realtime_stats 현재 시각 기준 실시간 통계 스냅샷 조회 없음
UTM 프리셋 (5개)
list_utm_presets 저장된 UTM 파라미터 프리셋 목록 조회 없음
get_utm_preset UTM 프리셋 단건 상세 조회 id
create_utm_preset 자주 사용하는 UTM 조합을 이름으로 저장 presetName
update_utm_preset 저장된 UTM 프리셋 수정 id
delete_utm_preset UTM 프리셋 삭제 id
커스텀 도메인 (1개)
list_custom_domains 커스텀 도메인 목록 조회 (URL/캠페인 생성 시 customDomainId 확인용) 없음

도구별 사용 예시

단축 URL 생성

대화 예시
👤 https://www.example.com/very/long/product/page 단축해줘

🤖 단축 URL을 생성했습니다.
   단축 URL : https://fplink.net/ex123
   원본 URL : https://www.example.com/very/long/product/page
   생성일시 : 2026-05-16 14:30:00
커스텀 별칭 지정
👤 https://example.com/sale 를 "summer-sale" 별칭으로 단축해줘

🤖 단축 URL을 생성했습니다.
   단축 URL : https://fplink.net/summer-sale

URL 통계 조회

대화 예시
👤 URL ID 42번의 이번 달 클릭 통계 보여줘

🤖 URL #42 클릭 통계 (2026-05-01 ~ 2026-05-16):
   총 클릭 수  : 1,234회
   일평균 클릭 : 77.1회
   최다 클릭일 : 2026-05-10 (198회)
   기기별 비율 : 모바일 68% / 데스크톱 32%

캠페인 생성

대화 예시
👤 "여름세일" 캠페인 만들어줘.
   대상 URL은 https://shop.example.com/summer
   별칭은 summer2026, 만료일은 2026-08-31

🤖 캠페인을 생성했습니다.
   캠페인명    : 여름세일
   캠페인 URL  : https://fplink.net/c/summer2026
   만료일      : 2026-08-31 23:59:59
   캠페인 ID   : 15

대시보드 요약

대화 예시
👤 현재 서비스 현황 요약해줘

🤖 FINGERPUSH.LINK 대시보드 요약:
   전체 단축 URL : 234개
   이번 달 클릭  : 12,847회
   활성 캠페인   : 8개
   사용 중인 앱  : 3개

URL 수정

대화 예시
👤 URL 42번의 원본 주소를 https://new.example.com/v2 로 바꾸고
   만료일을 2026-12-31로 설정해줘

🤖 URL #42 수정 완료:
   원본 URL  : https://new.example.com/v2
   만료일    : 2026-12-31T23:59:59
   단축 URL  : https://fplink.net/ex123
UTM 파라미터 일괄 수정
👤 URL 55번에 UTM source=kakao, medium=cpc, campaign=summer2026 붙여줘

🤖 URL #55 UTM 파라미터가 업데이트되었습니다.
   utm_source   : kakao
   utm_medium   : cpc
   utm_campaign : summer2026

URL 삭제

대화 예시
👤 URL 99번 삭제해줘

🤖 URL #99이(가) 삭제되었습니다.

캠페인 목록 조회

대화 예시
👤 "여름" 키워드가 포함된 캠페인 목록 보여줘

🤖 "여름" 캠페인 검색 결과 (3건):
   #15  여름세일     /c/summer2026   클릭 4,521회  만료 2026-08-31
   #18  여름이벤트   /c/summer-evt   클릭 1,203회  만료 2026-07-31
   #22  여름특가     /c/summer-hot   클릭   892회  만료 2026-09-15

앱 목록 조회

대화 예시
👤 등록된 앱 목록이랑 설치 수 알려줘

🤖 등록된 앱 (3개):
   #1  쇼핑앱 (iOS + Android)   누적 설치 12,340회  이번 달 +1,024
   #2  멤버십앱 (iOS)            누적 설치  3,210회  이번 달   +89
   #3  웹앱 (Web)                세션 8,920회        이번 달  +342

MAU 통계 조회

대화 예시 — 특정 월
👤 이번 달(2026년 5월) MAU 통계 보여줘

🤖 2026년 5월 MAU 통계:
   앱 #1  쇼핑앱    : MAU 8,234명  (전월 대비 +12.3%)
   앱 #2  멤버십앱  : MAU 1,891명  (전월 대비  +5.7%)
   앱 #3  웹앱      : MAU 5,102명  (전월 대비 +18.1%)
대화 예시 — 연도 전체
👤 2026년 MAU 월별 추이 알려줘

🤖 2026년 월별 MAU 요약:
   1월  6,102명  2월  6,891명  3월  7,340명
   4월  7,891명  5월  8,234명  ...

URL / 캠페인 단건 조회

대화 예시 — URL 상세
👤 URL 42번 딥링크 설정이랑 UTM 파라미터 전부 보여줘

🤖 URL #42 상세 정보:
   단축 URL     : https://fplink.net/ex123
   원본 URL     : https://example.com/product/summer
   iOS 딥링크   : myapp://product/summer
   Android 딥링크: myapp://product/summer
   utm_source   : naver
   utm_medium   : cpc
   utm_campaign : summer2026
   만료일       : 2026-08-31
대화 예시 — 캠페인 상세
👤 캠페인 15번 전체 설정 확인해줘

🤖 캠페인 #15 상세 정보:
   이름         : 여름세일 2026
   단축 URL     : https://fplink.net/c/summer2026
   원본 URL     : https://example.com/summer-sale
   OG 제목      : ☀️ 여름 최대 할인 이벤트
   OG 설명      : 최대 50% 할인, 지금 바로 확인하세요
   만료일       : 2026-08-31
   클릭 수      : 4,521회

캠페인 경유 앱 설치 통계

대화 예시
👤 캠페인 15번 통해서 앱 설치된 거 이번 달 통계 보여줘

🤖 캠페인 #15 앱 설치 통계 (2026-05-01 ~ 2026-05-21):
   iOS 설치     : 234건
   Android 설치 : 187건
   합계         : 421건
   일평균       : 20건

UTM 프리셋 관리

대화 예시 — 프리셋 목록 조회
👤 저장된 UTM 프리셋 목록 보여줘

🤖 UTM 프리셋 목록 (5개):
   #1  네이버_CPC       source=naver   medium=cpc
   #2  카카오_배너      source=kakao   medium=display
   #3  이메일_뉴스레터   source=email   medium=newsletter
   #4  인스타그램_피드   source=instagram medium=social
   #5  여름세일_네이버   source=naver   medium=cpc  content=summer_banner
대화 예시 — 프리셋 저장 후 URL 생성
👤 "카카오_CPC" 라는 이름으로 source=kakao, medium=cpc 프리셋 저장해줘

🤖 UTM 프리셋 "카카오_CPC"가 저장되었습니다. (ID: 6)

👤 방금 저장한 프리셋으로 https://example.com/product 단축 URL 만들어줘

🤖 단축 URL 생성 완료:
   단축 URL     : https://fplink.net/kk001
   원본 URL     : https://example.com/product?utm_source=kakao&utm_medium=cpc

조직별 연결 (멀티 조직)

각 조직의 Service API KEY를 별도로 설정하면 Claude Desktop에서 여러 조직을 동시에 관리할 수 있습니다. X-API-KEY 헤더에는 각 조직의 콘솔 > API 키 관리에서 발급한 X-API-KEY 값을 입력합니다.

claude_desktop_config.json — 다중 조직 예시
{
  "mcpServers": {
    "회사A-링크": {
      "url": "https://mcp.fingerpush.link/mcp/sse",
      "headers": { "X-API-KEY": "조직A의_X-API-KEY_값" }
    },
    "회사B-링크": {
      "url": "https://mcp.fingerpush.link/mcp/sse",
      "headers": { "X-API-KEY": "조직B의_X-API-KEY_값" }
    }
  }
}

각 연결은 독립적인 세션으로 관리되며, 서로 다른 조직의 데이터는 완전히 분리됩니다.

고도화 로드맵

현재 29개 도구가 제공됩니다. 도구 요청은 아래 고객센터로 남겨주세요.

피드백도구 요청
필요한 도구가 있으면 콘솔 내 고객센터 Q&A로 요청해 주세요. 우선순위에 반영하겠습니다.

트러블슈팅

Claude Desktop에서 도구 아이콘이 보이지 않아요

  • Claude Desktop을 완전히 종료 후 재시작하세요 (작업 표시줄 트레이 아이콘까지 종료)
  • JSON 문법 오류가 없는지 확인하세요 (jsonlint.com에서 검증)
  • API KEY에 앞뒤 공백이 없는지 확인하세요

"API KEY가 없습니다" 오류

  • 설정 파일에서 X-API-KEY 헤더 이름이 정확한지 확인하세요
  • 콘솔에서 API KEY가 활성 상태인지 확인하세요

연결이 자주 끊겨요 (SSE 재연결)

현재 MCP 서버는 App Engine Standard에 배포되어 있으며, 30초 간격으로 하트비트를 전송합니다. Claude Desktop은 SSE 연결이 끊기면 자동으로 재연결합니다. 재연결 시 API KEY는 설정 파일에서 자동으로 다시 전송되므로 별도 조치가 필요하지 않습니다.