Amplitude MCP Analytics 설정
MCP 서버의 모든 도구 호출을 Amplitude 이벤트로 만들어, 제품의 다른 Amplitude 데이터(리텐션, 수익, 웹/모바일 사용량)와 결합할 수 있도록 계측합니다.
권위 있는 SDK 참조는 패키지 README입니다:
https://github.com/amplitude/Amplitude-MCP-Analytics-Node (npm: @amplitude/mcp-analytics).
SDK는 프리뷰 상태이며 빠르게 진화합니다 — 항상 최신 README를 가져와 설치, API 형태, 설정 및 기본 이벤트에 대해 따르십시오. 암기한 코드 조각이나 이 스킬의 요약에 의존하지 마십시오. SDK API 세부 사항은 README가 우선합니다.
네 단계가 있습니다. 1~2단계는 필수이며 README에 문서화되어 있습니다 — 이 스킬은 따라야 할 섹션과 확인해야 할 불변 조건을 알려줍니다. 3~4단계는 강력히 권장되며 여기에 완전히 문서화되어 있습니다. SDK README가 의도적으로 다루지 않는 SDK 외부의 변경(서버의 도구 스키마 및 제품의 웹 앱)이 필요하기 때문입니다.
순서대로 수행하십시오: 1단계(도구 호출) → 2단계(식별) → 3단계(근거) → 4단계(UTM, 서버가 링크를 반환하는 경우에만). "완료"라고 말하기 전에 식별을 올바르게 설정하십시오 — 모든 하위 항목이 이에 의존합니다.
시작하기 전에
다음 사항을 확인하십시오:
- 이것은
@modelcontextprotocol/sdk로 구축된 Node/TypeScript MCP 서버입니다. 이 SDK는 다른 언어/런타임을 지원하지 않습니다. - 사용자가 이벤트가 전송될 프로젝트에 대한 Amplitude API 키를 가지고 있거나 얻을 수 있습니다.
- 저장소에서 사용하는 패키지 관리자(pnpm/npm/yarn) — 설치 명령어를 조정하십시오.
1단계 — SDK 설치 및 도구 호출 추적 (필수)
README를 가져와 설치 및 빠른 시작 섹션을 따르십시오. 항상 최신 게시 버전을 설치하십시오 (예: pnpm add @amplitude/mcp-analytics@latest) — 기억에서 버전을 고정하지 말고, 이 스킬의 설치 명령어를 재현하지 마십시오.
연결 후 확인해야 할 불변 조건(README가 각각 설명):
analytics.instrumentServer(server, ...)는server.connect()전에 실행됩니다 — 순서가 중요합니다.- 모든 도구 핸들러가
analytics.instrumentTool(...)로 래핑됩니다. 래핑되지 않은 도구는 추적되지 않습니다. 래퍼는 핸들러와 동일한 형태를 가지며 서버가 바인딩되지 않은 경우 무작동 패스스루이므로 방어적으로 래핑해도 안전합니다. - 기본 이벤트는 모두
[MCP]접두사를 가지므로 제품의 기존 Amplitude 이벤트와 충돌하지 않습니다. 현재 이벤트 세트 및 속성은 README의 기본 이벤트 테이블(및 저장소의docs/events.md)을 참조하십시오.
선택 사항: instrumentTool/instrumentServer의 extra를 통해 안정적인 사용자 정의 차원(요금제, 팀, 기능 플래그)을 첨부할 수 있습니다 — README의 사용자 정의 이벤트 속성 섹션을 참조하십시오.
2단계 — 식별 올바르게 설정 (필수, 1단계를 "완료"라고 부르기 전에 수행)
MCP 이벤트는 제품이 웹/모바일에서 Amplitude로 이미 보내는 것과 **동일한 user_id**를 전달해야 합니다. 이를 건너뛰면 MCP 사용량이 연결 해제된 인구로 표시되어 제품 데이터에 결합할 수 없습니다 — 이는 통합의 대부분의 목적을 무력화합니다.
현재 API에 대해 README의 식별 섹션을 따르십시오: 서버 수준 바인딩, 핸들러 내에서의 요청별 setIdentity(), 요청의 authInfo 클레임에서의 옵트인 resolveIdentity 매핑을 제공합니다. 서버의 인증 모델에 맞는 것을 선택하십시오.
사용자에게 알려야 할 한 가지 동작: 완전히 익명의 앵커 없는 이벤트는 집계 전용 추적을 위해 명시적으로 emitAnonymousEvent: true를 옵트인하지 않는 한 기본적으로 드롭됩니다 (사용자로 계산되지 않음) — 이 설정을 켜기 전에 물어보십시오. 계산되는 항목이 변경되기 때문입니다.
3단계 — 근거 캡처 (권장)
사람이 버튼을 클릭하는 것과 달리, 에이전트는 도구를 호출한 이유를 알려줄 수 있습니다. 이를 캡처하면 데이터가 "무슨 일이 일어났는가"에서 "사용자가 무엇을 하려 했는가"로 전환됩니다.
SDK 측은 한 번의 호출(analytics.setRationale(...) — README의 근거 섹션 참조)이지만, SDK는 도구 입력에서 근거를 직접 읽지 않습니다: 근거가 서버에 도달하는 방식은 이 스킬이 구현하는 서버 측 규칙입니다. 전투에서 검증된 패턴은 스키마 주입입니다 — 모든 도구의 입력 스키마에 선택적 rationale 필드를 추가합니다. 매개변수가 에이전트가 이미 읽는 스키마에 설명되어 있기 때문에, 클라이언트 측 변경 없이 모든 클라이언트에서 자발적으로 채워집니다:
// 모든 도구의 입력 스키마에 추가 (zod 예제):
rationale: z
.string()
.optional()
.describe(
'이 도구를 호출하는 이유와 결과에서 무엇을 배울 것으로 예상하는지에 대한 간략한 설명.',
),
그런 다음 계측된 핸들러 내에서 이를 읽고 SDK에 전달합니다:
analytics.instrumentTool(async (args, extra) => {
if (typeof args.rationale === 'string') {
analytics.setRationale(args.rationale);
}
return doWork(args);
}, { name: 'search' });
필드를 선택 사항으로 만들면 에이전트가 생략해도 아무것도 깨지지 않습니다. 예약된 [MCP] Rationale 속성으로 전송됩니다(1,000자로 잘림; 마지막 쓰기가 우선). 샘플이 아닌 모든 도구에 적용할 가치가 있습니다.
4단계 — 아웃바운드 링크에 UTM 태그 추가 (권장, 서버가 URL을 반환하는 경우에만)
이 단계는 완전히 SDK 외부에 있습니다 — 서버가 URL을 구축하는 방식을 변경하며 제품의 웹 측 분석에 의존합니다. SDK README에서는 다루지 않습니다.
도구 응답에 링크(대시보드, 문서, 제품 페이지)가 포함된 경우, 서버를 떠나기 전에 태그를 추가하여 클릭스루가 직접 방문으로 표시되지 않고 MCP/에이전트 트래픽으로 귀속되도록 하십시오:
function addUtmParams(url: string, clientName?: string): string {
const u = new URL(url);
u.searchParams.append('utm_source', 'mcp');
u.searchParams.append('utm_medium', 'referral');
// 연결된 클라이언트(예: "Claude", "Cursor"), 알고 있는 경우:
u.searchParams.append('utm_content', clientName ?? 'unknown');
return u.toString();
}
도구 응답의 모든 URL 구축 경로를 이와 같은 하나의 중앙 함수를 통해 라우팅하십시오 — 태그가 없는 단일 링크는 해당 흐름의 기여 분석을 깨뜨립니다.
전제 조건 (사용자에게 명시적으로 알리십시오): 이는 웹 분석이 페이지 조회 이벤트(또는 사이트가 방문 시 발생시키는 이벤트)에서 UTM 매개변수를 캡처하는 경우에만 작동합니다. Amplitude의 Browser SDK 2는 기본적으로 이 작업을 수행합니다 — 마케팅 기여도 추적을 참조하십시오(UTM, 리퍼러 및 클릭 ID 매개변수가 기본적으로 캡처됨). 사용자 정의 페이지 조회 추적기를 사용하는 경우 UTM 값도 해당 이벤트에 포함되는지 확인해야 합니다. 그렇지 않으면 MCP 태그가 지정된 클릭을 결합할 대상이 없습니다.
관련 Amplitude 문서:
- Browser SDK 2 — 마케팅 기여도 추적 (웹 측 UTM 캡처, 이 단계의 구현 절반)
- 마케팅 분석을 위한 세션, 채널 및 기여도 (태그된 트래픽이 채널 분석이 되는 방법)
- 자동 캡처 (페이지 조회 등)
계측 후
이벤트가 흐르기 시작하면, 코딩 에이전트를 Amplitude의 게시된 analyze-mcp-server 스킬로 안내하여 의도 클러스터링을 실행하고 의도별 도구 호출 오류 패턴을 표면화하십시오. (이 프로젝트에 mcp-intent-error-analysis 스킬이 설치된 경우, 그것을 사용하십시오 — 사용자가 데이터를 흐르게 하고 분석하려 할 때 이 분석을 여기서 중복하지 말고 사용하십시오.)
표시해야 할 일반적인 실수
- 오래된 API 조각을 따르는 대신 현재 README를 사용 — 새로 가져오십시오. SDK는 프리뷰 상태이며 빠르게 움직입니다.
- 최신 릴리스 대신 고정된/오래된 버전을 설치.
server.connect()후에instrumentServer()호출 — 반드시 전에 해야 합니다.- 일부 도구 핸들러만 래핑하고 다른 것은 래핑하지 않음 — 모든 도구에
instrumentTool이 필요합니다. - 웹/모바일에서 사용되는 것과 일치하지 않는
user_id전송 — 결합성을 깨뜨리며, 통합의 핵심 목적입니다. - 사용자가 이해하지 못한 채
emitAnonymousEvent: true를 켜면 앵커 없는 트래픽으로 집계가 부풀려집니다. - UTM 전제 조건(웹 측 캡처)을 잊고 링크 태그만으로 충분하다고 가정.