GrowSurf MCP 서버

공식 GrowSurf 명령줄 인터페이스(CLI) 및 오픈소스 Model Context Protocol(MCP) 서버로, 안내된 단계와 안전한 REST API 래퍼를 통해 GrowSurf 추천 및 제휴 프로그램을 구현할 수 있습니다.

AI 에이전트에 연결하면, 일반 언어로 에이전트가 추천 또는 제휴 프로그램을 만들고, 보상을 구성하고, 추적을 설치하고, 참가자를 추가 및 관리하고, 분석을 읽을 수 있습니다. 모든 작업은 GrowSurf REST API를 기반으로 합니다.

• GrowSurf에 대해 자세히 알아보기: https://growsurf.com

• 이 MCP 서버에 대해 자세히 알아보기: https://docs.growsurf.com/build-with-ai

대상 사용자

이 MCP 서버는 다음을 위한 것입니다:

• MCP 호환 도구(Claude Code, Codex, Cursor, Copilot 및 기타 MCP 클라이언트)를 사용하는 개발자

• 안내된 AI 지원 GrowSurf 통합을 원하는 팀

이 MCP 서버는 다음을 위한 것이 아닙니다:

• 로컬 stdio 설치를 원하는 브라우저 전용 사용자. ChatGPT 웹, Claude.ai, Claude Desktop은 로컬 MCP 서버를 실행하지 않지만, 세 가지 모두 https://mcp.growsurf.com의 호스팅 원격 커넥터를 통해 GrowSurf에 연결됩니다. 전체 클라이언트 목록과 설정은 https://docs.growsurf.com/build-with-ai#mcp에서 확인하세요.

Related MCP server: SurfRank MCP Server

제공 기능

• 안내된 통합:

  • 유니버설 코드 설치

  • 네이티브 iOS/Android SDK 구현 안내

  • 네이티브 GrowSurf Window 안내

  • 가입 흐름

  • 자격 충족 액션 흐름

  • 제휴 판매/거래 추적

  • 웹훅

• 에이전트 레시피:

  • 추천 프로그램 생성, 제휴 프로그램 생성, 위젯 삽입, 프로그램 및 참가자 목록 조회 및 가져오기, 보상 구성, 웹훅 연결, 분석 읽기를 위한 MCP 프롬프트

  • skills/growsurf-agent-toolkit의 설치 가능한 에이전트 스킬 번들

  • 패치 전에 스타터 디자인, 이메일, 옵션, 설치, 보상 및 GrowSurf Window 콘텐츠를 검토하도록 안내

  • 스타터 콘텐츠 및 구성 검토를 위한 원샷 프로그램 생성 평가 프롬프트 및 승인 검사

• Happy-Path REST API 래퍼:

  • 기존 자격 증명 없이 계정 생성 및 API 키 받기

  • 바인딩된 팀 읽기 및 이름 변경, 팀 검증 요청, 팀 소유자의 검증 이메일 재전송

  • 캠페인 목록 조회 및 가져오기

  • 캠페인 분석 가져오기(합계, 선택적 기간별 시계열, 이메일 지표, 이전 기간 합계, 상태 수 및 비율)

  • 프로그램(캠페인) 생성, 업데이트 및 복제

  • 캠페인 보상 목록 조회, 생성, 업데이트 및 삭제

  • 디자인, 이메일, 옵션 및 설치 구성 가져오기/업데이트

  • 사용자가 시각적 증거를 명시적으로 요청할 때 임시 GrowSurf 미리보기 스크린샷 캡처

  • 프로그램 웹훅 목록 조회, 생성, 업데이트, 삭제 및 테스트

  • 참가자 목록 조회, 가져오기 및 추가

  • 참가자 업데이트, 참가자에게 이메일 보내기, 참가자의 분석 및 활동 로그 가져오기

  • 추천 크레딧 트리거(추천 프로그램용), 선택적 지연 보상(1-90일)

  • 보류 중인 지연 추천 트리거 취소(추천 프로그램용)

  • 제휴 판매/거래 기록(제휴 프로그램용)

  • 로그인한 네이티브 앱 사용자를 위한 모바일 참가자 토큰 생성

• 공식 API 라이브러리 스니펫:

  • TypeScript

  • Python

  • PHP

  • Ruby

  • Java

• 헬퍼:

  • 참가자 자동 인증 HMAC 해시 계산

  • 웹훅 페이로드 정규화

  • 웹훅 중복 제거를 위한 최선 노력 멱등성 키 생성

요구 사항

• Node.js 22+

• 호스팅 OAuth를 위한 GrowSurf 계정

• 로컬 stdio 설정 또는 수동 API 키 원격 설정을 위한 GrowSurf API 키. 에이전트가 사용하려는 도구와 프로그램에 대한 액세스 권한이 있으면 범위가 지정된 키도 작동합니다.

• 캠페인 범위 도구를 위한 캠페인(프로그램) ID. GROWSURF_CAMPAIGN_ID를 기본값으로 설정하거나, campaignId 인수를 전달하여 특정 프로그램을 대상으로 하거나, growsurf_list_campaigns를 호출하여 사용 가능한 프로그램을 찾으세요. 새로 생성된 프로그램의 경우 growsurf_create_campaign이 반환한 id를 다른 도구에 전달하세요.

• 정적 안내/스니펫 도구는 자격 증명 없이 실행 가능

• 예외: growsurf_create_account는 API 키가 필요 없습니다. 새 계정을 만들고 API 키를 반환합니다. 팀 수준 도구는 캠페인 ID가 필요 없습니다.

• 나열된 모든 도구는 표준 MCP 읽기 전용, 파괴적, 멱등성 및 오픈 월드 안전 힌트를 게시합니다. 범위가 지정된 비즈니스 작업은 계속 사용 가능하며, API 키 회전은 의도적으로 MCP 도구가 아닙니다. 키는 GrowSurf 설정 또는 직접 REST/SDK 클라이언트를 통해 회전하세요.

공식 CLI

npm 패키지는 growsurf-mcp 명령을 설치합니다. 전역 설치 없이 실행하세요:

npx -y @growsurfteam/growsurf-mcp

CLI는 GrowSurf의 로컬 stdio MCP 서버를 시작합니다. API 기반 작업에는 GROWSURF_API_KEY를, 기본 프로그램에는 GROWSURF_CAMPAIGN_ID를 설정하세요. 공개 개발자 리소스와 정적 통합 안내는 자격 증명 없이 작동합니다.

stdio 서버를 시작하지 않고 설치된 명령을 검사하려면:

npx -y @growsurfteam/growsurf-mcp --help
npx -y @growsurfteam/growsurf-mcp --version

지원되는 MCP 호스트

호스트가 원격 Streamable HTTP with OAuth를 지원하는 경우 권장 경로는 https://mcp.growsurf.com의 GrowSurf 호스팅 OAuth 엔드포인트입니다. 호스트가 stdio 프로세스 또는 수동 API 키 설정이 필요한 경우 로컬 npx 서버를 사용하세요. 아직 GrowSurf 계정이 없으신가요? 에이전트가 자격 증명 없이 호스팅 온보딩 엔드포인트 https://mcp.growsurf.com/onboard에 연결하여 growsurf_create_account를 호출해 가입할 수 있습니다.

GrowSurf MCP 서버는 모든 MCP 호환 호스트에서 작동합니다. 아래 예시는 몇 가지 구성 기반 및 CLI 호스트를 다룹니다. 지원되는 클라이언트의 전체 최신 목록(ChatGPT 웹, Claude.ai, Claude Desktop, GitHub Copilot, Gemini CLI, Devin Desktop, Cline 포함)과 단계별 설정은 https://docs.growsurf.com/build-with-ai#mcp를 참조하세요.

• Cursor

• Claude Code (CLI 기반)

• Antigravity

• Codex (CLI 기반)

Cursor

1. Cursor의 전역 MCP 구성 파일 ~/.cursor/mcp.json을 열거나 생성합니다.

2. 호스팅 OAuth 엔드포인트를 사용하여 growsurf라는 서버를 추가합니다:

{
  "mcpServers": {
    "growsurf": {
      "type": "http",
      "url": "https://mcp.growsurf.com"
    }
  }
}

로컬 stdio를 대신 사용하려면:

{
  "mcpServers": {
    "growsurf": {
      "command": "npx",
      "args": ["-y", "@growsurfteam/growsurf-mcp"],
      "env": {
        "GROWSURF_API_KEY": "YOUR_API_KEY",
        "GROWSURF_CAMPAIGN_ID": "YOUR_CAMPAIGN_ID"
      }
    }
  }
}

Claude Code (CLI 기반)

터미널을 열고 Claude Code를 호스팅 OAuth 엔드포인트에 연결합니다:

claude mcp add --transport http --scope user growsurf https://mcp.growsurf.com
claude mcp login growsurf

로컬 stdio를 대신 사용하려면 서버를 Claude Code에 직접 설치합니다:

claude mcp add growsurf \
  -e GROWSURF_API_KEY=your_api_key \
  -e GROWSURF_CAMPAIGN_ID=your_campaign_id \
  -- npx -y @growsurfteam/growsurf-mcp

Antigravity

1. Antigravity를 엽니다.

2. 오른쪽 패널의 … 메뉴를 클릭하고 MCP Servers를 선택합니다.

3. Manage MCP Servers > View raw config를 클릭합니다.

4. 권장: mcp_config.json 파일에 호스팅 OAuth 엔드포인트를 추가합니다:

{
  "mcpServers": {
    "growsurf": {
      "serverUrl": "https://mcp.growsurf.com"
    }
  }
}

5. 구성을 저장하고 Settings > Customizations를 연 다음 GrowSurf에 대해 Authenticate를 선택합니다.

로컬 stdio를 대신 사용하려면:

{
  "mcpServers": {
    "growsurf": {
      "command": "npx",
      "args": ["-y", "@growsurfteam/growsurf-mcp"],
      "env": {
        "GROWSURF_API_KEY": "YOUR_API_KEY",
        "GROWSURF_CAMPAIGN_ID": "YOUR_CAMPAIGN_ID"
      }
    }
  }
}

Codex

권장: Codex를 호스팅 OAuth 엔드포인트에 연결합니다:

codex mcp add growsurf --url https://mcp.growsurf.com
codex mcp login growsurf

또는 ~/.codex/config.toml을 생성하거나 편집합니다:

[mcp_servers.growsurf]
url = "https://mcp.growsurf.com"

로컬 stdio를 대신 사용하려면 다음을 추가합니다:

[mcp_servers.growsurf]
command = "npx"
args = ["-y", "@growsurfteam/growsurf-mcp"]

[mcp_servers.growsurf.env]
GROWSURF_API_KEY = "YOUR_API_KEY"
GROWSURF_CAMPAIGN_ID = "YOUR_CAMPAIGN_ID"

또는 CLI에서 로컬 stdio를 구성합니다:

codex mcp add growsurf \
  --env GROWSURF_API_KEY=YOUR_API_KEY \
  --env GROWSURF_CAMPAIGN_ID=YOUR_CAMPAIGN_ID \
  -- npx -y @growsurfteam/growsurf-mcp

구성

MCP 서버를 실행할 때 다음 환경 변수를 설정하세요:

• GROWSURF_API_KEY (시작 시 선택 사항; API 호출 도구에 필요. 해당 도구가 필요한 범위와 프로그램 액세스 권한이 있는 키를 사용하세요)

• GROWSURF_CAMPAIGN_ID (선택 사항; 캠페인 범위 도구의 기본 프로그램. 도구의 campaignId 인수가 이를 재정의하므로 단일 서버가 모든 프로그램에서 작동할 수 있습니다)

• GROWSURF_API_BASE_URL (선택 사항; 기본값은 https://api.growsurf.com/v2. 다른 GrowSurf API 원본을 호출해야 하는 로컬 또는 호스팅 MCP 게이트웨이에 유용)

• GROWSURF_PARTICIPANT_AUTH_SECRET (선택 사항; 해시 헬퍼에서 사용)

• GROWSURF_WEBHOOK_TOKEN (선택 사항; 자체 웹훅 URL 토큰 체계에 사용)

npx로 실행

이 패키지를 게시한 후 고객은 다음을 실행할 수 있습니다:

npx @growsurfteam/growsurf-mcp

이 저장소의 로컬 개발용:

npm install
npm run build
node dist/cli.js

MCP 도구

모든 도구는 MCP 출력 스키마를 선언하고 structuredContent를 반환하므로 호스트가 각 도구의 결과 형태를 알 수 있습니다. REST 도구는 API 응답을 반환하고(이전 클라이언트용 JSON 텍스트 블록 포함), 안내 및 스니펫 도구는 markdown 아래에 마크다운 문서를 반환합니다.

안내된 통합

• growsurf_integration_guide GrowSurf 추천 또는 제휴 프로그램 구현을 위한 단계별 안내.

• growsurf_mobile_sdk_guide 속성, shareUrl, trackShare 및 네이티브 GrowSurf Window를 위한 네이티브 iOS/Android SDK 안내.

• growsurf_api_library_snippets TypeScript, Python, PHP, Ruby 및 Java용 공식 REST API 라이브러리 스니펫.

• growsurf_get_integration_connect_link 특정 통합의 연결 패널(Stripe, PayPal, Tango Card, Mailchimp 등)을 여는 대시보드 링크를 가져옵니다. 사용자가 연결을 원할 때 전달하세요. 연결은 API가 아닌 대시보드에서 이루어집니다.

클라이언트 및 UI 스니펫

• growsurf_client_snippets JavaScript SDK, GrowSurf Window 및 삽입 가능한 예제. 삽입 가능한 UI를 배치하거나 스타일링할 때 프론트엔드 디자인 워크플로우를 사용하라는 알림이 포함됩니다.

• growsurf_embeddable_element_snippet 특정 GrowSurf 삽입 가능한 요소에 대한 HTML 스니펫.

• growsurf_grsf_config_snippet window.grsfConfig 및 참가자 자동 인증 구성을 위한 <head> 스니펫.

계정 온보딩

• growsurf_create_account GrowSurf 계정을 만들고 API 키를 받습니다. GROWSURF_API_KEY가 필요 없는 유일한 도구입니다. 반환된 키는 한 번만 표시되며 소유자가 이메일을 검증할 때까지 잠겨 있습니다(403 EMAIL_NOT_VERIFIED_ERROR). 키는 소유자가 대시보드에 처음 로그인할 때 회전됩니다. 계정을 만들면 계정 보유자를 대신하여 GrowSurf의 서비스 약관 및 개인정보 보호정책에 동의하는 것입니다.

팀

• growsurf_get_team API 키 또는 OAuth 연결에 바인딩된 팀을 가져옵니다. GrowSurf 검증 상태를 포함합니다.

• growsurf_update_team 바인딩된 팀의 표시 이름을 업데이트합니다.

• growsurf_request_team_verification GrowSurf에 바인딩된 팀 검증을 요청합니다. 프로그램이 참가자에게 이메일을 보내기 전에 필요합니다.

• growsurf_resend_team_owner_verification_email 바인딩된 팀 소유자의 이메일 주소를 공개하지 않고 검증 이메일을 재전송합니다.

API 및 추적

• growsurf_get_campaign 캠페인 구성을 가져옵니다.

• growsurf_list_campaigns 자격 증명에 사용 가능한 프로그램을 나열합니다. 캠페인 범위 도구를 호출하기 전에 이 도구를 사용하여 campaignId를 찾으세요.

• growsurf_get_campaign_analytics 프로그램 분석을 가져옵니다. 선택적으로 기간별 series, 비교, 상태, 비율, 그리고 include=email을 통한 이메일 전송 및 참여 데이터를 포함할 수 있습니다.

• growsurf_create_campaign 유형에 적합한 시작 콘텐츠와 선택적 인라인 보상으로 새 프로그램(캠페인)을 생성합니다(GROWSURF_CAMPAIGN_ID가 아닌 GROWSURF_API_KEY만 필요). 패치 전에 시드된 Design, Emails, Options, Installation, 보상 및 GrowSurf Window 콘텐츠를 검토하세요.

• growsurf_agent_program_creation_eval 시작 콘텐츠, 보수적인 보상, 구성 검토, 프론트엔드 설치 증명, 깔끔한 공개 카피에 대한 일회성 프로그램 생성 평가 프롬프트와 승인 검사를 생성합니다.

• growsurf_update_campaign 프로그램의 식별 정보와 수명 주기를 업데이트합니다: 이름, 회사 브랜딩, 상태(보낸 필드만 변경됨).

• growsurf_clone_campaign 프로그램을 새 DRAFT 프로그램으로 복제합니다(통합 및 자격 증명은 복사되지 않음).

• growsurf_list_campaign_rewards 프로그램에 구성된 보상을 나열합니다.

• growsurf_create_campaign_reward 캠페인 보상을 생성합니다.

• growsurf_update_campaign_reward 보상 키로 캠페인 보상을 업데이트합니다.

• growsurf_delete_campaign_reward 보상 키로 캠페인 보상을 삭제합니다.

• growsurf_get_campaign_design / growsurf_update_campaign_design Program Editor Design 탭과 지급 대상 확인 페이지 카피를 포함한 디자인 구성을 읽거나 패치합니다.

• growsurf_get_campaign_emails / growsurf_update_campaign_emails Program Editor Emails 탭 구성을 읽거나 패치합니다.

• growsurf_get_campaign_options / growsurf_update_campaign_options Program Editor Options 탭 구성을 읽거나 패치합니다.

• growsurf_get_campaign_installation / growsurf_update_campaign_installation Program Editor Installation 탭 구성을 읽거나 패치합니다.

• growsurf_capture_referral_flow_screenshots 사용자가 시각적 증거를 명시적으로 요청한 후 현재 프로그램에 대한 임시 GrowSurf 미리보기 스크린샷을 캡처합니다. 이 도구는 통제된 추천인 Window와 추천된 친구 경험을 반환합니다. 사용자가 설치한 사이트를 증명하려면 브라우저 자동화를 대신 사용하세요.

• growsurf_list_campaign_webhooks 프로그램의 웹훅을 나열합니다(비밀은 절대 반환되지 않음).

• growsurf_create_campaign_webhook 프로그램에 웹훅을 추가합니다(이벤트 및 쓰기 전용 서명 비밀 포함).

• growsurf_update_campaign_webhook ID로 웹훅을 업데이트합니다(primary는 프로그램의 기본 웹훅).

• growsurf_delete_campaign_webhook ID로 웹훅을 제거합니다.

• growsurf_test_campaign_webhook 저장된 URL과 비밀을 사용하여 웹훅에 라이브 테스트 이벤트를 보냅니다.

• growsurf_add_participant 가입 중 참가자(또는 추천된 참가자)를 추가합니다.

• growsurf_list_participants 현재 프로그램의 참가자를 nextId로 페이지네이션하여 나열합니다. 참가자 범위 도구를 호출하기 전에 이 도구를 사용하여 참가자 ID를 찾으세요.

• growsurf_get_participant GrowSurf 참가자 ID 또는 이메일 주소로 참가자 한 명을 가져옵니다.

• growsurf_update_participant ID 또는 이메일로 참가자를 업데이트합니다(내부 notes 포함).

• growsurf_bulk_delete_participants 한 번의 요청으로 최대 200명의 참가자를 영구 삭제합니다(ID 및/또는 이메일, 혼합 목록 허용). 각 행에 대해 DELETED/NOT_FOUND/DUPLICATE/ERROR 결과를 반환합니다. 되돌릴 수 없음 — 참가자의 추천, 보상, 커미션 및 지급 기록을 제거합니다.

• growsurf_email_participant 구성된 템플릿 또는 자유 형식의 제목/본문을 사용하여 참가자에게 이메일을 보냅니다.

• growsurf_get_participant_analytics 한 참가자의 참여도, 순위, 공유, 제휴 수익, 커미션, 지급 및 선택적 이메일 지표를 가져옵니다. include=series, include=email 또는 둘 다 쉼표로 구분하여 사용하세요.

• growsurf_get_participant_activity_logs 참가자의 활동 로그를 나열합니다(오프셋/한도 페이지네이션).

• growsurf_trigger_referral 추천을 트리거합니다(추천 프로그램 전용). 선택적으로 delayInDays(1-90)를 전달하여 보상 지급 전에 N일 동안 크레딧을 보류할 수 있습니다(예: 환불 기간을 커버하기 위해).

• growsurf_cancel_delayed_referral 지연 기간이 경과하기 전에 보류 중인 지연 추천 트리거를 취소합니다(예: 환불/취소 시).

• growsurf_get_participant_payout_destination 프로그램에 활성화된 모든 제공자(PayPal 및/또는 Wise)에 대한 참가자의 지급 대상 상태를 가져옵니다: 제공자별 상태, 확인된 지급 이메일, 법적 수취인 유형 및 수리 사유.

• growsurf_request_participant_payout_destination_confirmation 참가자에게 제공자의 지급 대상을 확인하도록 요청합니다 — 일회성 확인 링크를 보냅니다(참가자만 확인할 수 있음).

• growsurf_record_sale 제휴 판매 또는 거래를 기록합니다(제휴 프로그램 전용).

• growsurf_refund_transaction 기록된 거래에 대한 수정(환불, 부분 환불 또는 차지백)을 기록합니다. 추천인의 커미션을 취소하거나 조정합니다(제휴 프로그램 전용). growsurf_record_sale의 역연산입니다.

• growsurf_create_mobile_participant_token 참가자를 생성하거나 가져온 다음, 로그인한 모바일 사용자를 위한 참가자 범위 모바일 SDK 토큰을 생성합니다.

헬퍼

• growsurf_participant_auth_hash 참가자 자동 인증 HMAC 해시를 생성합니다(참가자를 자동으로 인증하기 위해).

• growsurf_webhook_normalize 웹훅 페이로드를 정규화하고 멱등성 키를 생성합니다(웹훅 전달을 중복 제거하기 위해).

웹훅

GrowSurf 웹훅은 참가자, 추천, 보상 또는 거래와 같은 새 객체가 생성될 때와 같은 중요한 추천 또는 제휴 이벤트가 발생할 때 서버에 알립니다. 일반적인 사용 사례는 다음과 같습니다:

• 보상을 자동으로 이행

• 내부 포인트 또는 크레딧 시스템 유지

• 참가자 및 추천 데이터를 데이터베이스에 동기화

중복 전달 처리

동일한 이벤트가 두 번 이상 도착할 수 있으므로 웹훅 핸들러는 멱등적이어야 합니다. 시스템에서 무엇이든 변경하기 전에 멱등성 키를 저장하세요.

웹훅 보안 및 멱등성

웹훅에 secret이 구성된 경우 GrowSurf는 웹훅 전달에 서명합니다: 각 전달에는 해당 비밀로 계산된 GrowSurf-Signature HMAC 헤더가 포함됩니다(비밀은 쓰기 전용이며 절대 반환되지 않음). 웹훅을 안전하게 사용하려면 다음을 권장합니다:

• 웹훅에 secret을 설정하고 수신 시 GrowSurf-Signature 헤더를 검증

• 페이로드 형태와 예상 이벤트 유형 검증

• 동일한 이벤트가 두 번 이상 도착할 수 있으므로 멱등성 키를 사용하여 웹훅 이벤트 중복 제거

GrowSurf MCP 서버는 웹훅 페이로드를 정규화하고 최선의 멱등성 키를 생성하여 안전한 웹훅 처리를 단순화하는 헬퍼 도구(growsurf_webhook_normalize)를 제공합니다.

개발 및 테스트

npm run dev
npm test

추가 리소스

다음에서 개발자 문서를 읽으세요:

• JavaScript SDK 참조: https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference

• REST API 참조: https://docs.growsurf.com/developer-tools/rest-api/api-reference

• REST API 라이브러리: https://docs.growsurf.com/developer-tools/rest-api/api-libraries

• 네이티브 모바일 가이드: https://docs.growsurf.com/getting-started-for-native-mobile

• iOS SDK: https://docs.growsurf.com/developer-tools/ios-sdk

• Android SDK: https://docs.growsurf.com/developer-tools/android-sdk

• GrowSurf 시작하기: https://docs.growsurf.com/getting-started

GrowSurf MCP 서버는 GrowSurf 고객이 추천 프로그램과 제휴 프로그램을 빠르게 구현할 수 있도록 도와줍니다.