Jam MCP, API, CLI - Jam을 AI 에이전트에 추가하는 방법

요약 (TL;DR)

• Jam의 호스팅된 MCP 서버가 주요 프로그래밍 인터페이스입니다: 33개의 문서화된 도구 중 두 개는 별칭(alias)입니다. Jam은 범용 REST API 레퍼런스를 게시하지 않습니다.
• 직접적인 경로는 Jam CLI와 웹훅을 사용합니다. 이는 MCP가 부족한 기능을 추가합니다: 파일이나 Playwright 트레이스에서 Jam 생성, 화면 녹화, 그리고 jam.created 이벤트에 반응하는 기능입니다.
• Jam MCP 인증은 OAuth 전용이 아닙니다. 개인 액세스 토큰(PATs)은 헤드리스 클라이언트를 지원하지만, 각각은 하나의 사용자 및 워크스페이스에 연결되며 1년 이내에 만료됩니다.
• 다중 테넌트 에이전트의 경우, 두 경로 모두 사용자당 하나의 Jam 자격 증명을 남기며, 저장(storage), 새로고침(refresh), 취소(revocation)는 사용자가 직접 처리해야 합니다.
• Scalekit의 Jam MCP 커넥터는 각 사용자의 토큰을 금고에 보관하고 새로고침하며, 모든 execute_tool 호출을 기록하고, 가상 MCP 서버를 통해 에이전트 역할별로 도구를 범위 지정합니다.

왜 Jam은 일반적인 MCP 대 API 선택 기준을 무너뜨리는가?

AI 에이전트는 Jam을 열고 그 안에서 유용한 작업을 수행해야 합니다: 실패한 요청 읽기, 콘솔 오류 상관관계 분석, 티켓 등록 등입니다. Jam은 호스팅된 MCP 서버, CLI, 그리고 웹훅을 제공합니다. 하지만 대부분의 팀이 가장 먼저 찾는 것, 즉 문서화된 공개 REST API는 제공하지 않습니다. 이로 인해 일반적인 MCP 대 API 질문 자체가 뒤바뀝니다. Jam에게 있어 “API”란 CLI 바이너리와 이벤트 스트림이며, MCP 서버가 대부분의 기능을 담고 있는 곳입니다. 여기에서 선택하는 방법과 어느 경로를 택하든 여전히 사용자가 소유해야 하는 것이 무엇인지 설명합니다.

Jam MCP와 대안들이 실제로 무엇인지

비교되는 두 가지 객체가 있지만, 가장 일반적인 MCP 대 API 비교는 아닙니다.

Jam MCP

Jam의 MCP 서버는 Jam이 호스팅하고 유지 관리하는 원격 서버이며, 2025년 8월부터 사용 가능합니다. Jam의 MCP 문서는 Claude, ChatGPT, Claude Code, Cursor, VS Code, Windsurf, Codex, OpenCode에 대한 설정 방법을 다룹니다. 에이전트는 Jam 링크 또는 ID를 받으며, 도구들은 해당 Jam의 녹화, 콘솔, 네트워크 및 이벤트 데이터를 컨텍스트로 로드합니다.

인증(Auth)은 두 가지 형태를 취합니다. 대화형 클라이언트(Interactive clients)는 브라우저 OAuth 흐름을 완료하고 작업 공간(workspace)을 선택합니다. 헤드리스 클라이언트는 PAT(Personal Access Token)를 베어러 토큰(bearer token)으로 전송합니다. 어느 쪽이든, MCP는 사용자의 기존 Jam 권한을 미러링합니다. 즉, 사용자가 Jam 웹 또는 모바일 앱에서 이미 볼 수 없는 것은 아무것도 부여하지 않습니다.

CLI와 웹훅, REST 레퍼런스는 아닙니다

2026년 9월 현재, Jam의 문서 인덱스에는 공개 REST API 레퍼런스가 없습니다. MCP가 아닌 표면(non-MCP surface)은 두 가지입니다. Jam CLI는 macOS, Linux, Windows용 네이티브 바이너리로서 모든 읽기 및 쓰기를 명령어 형태로 노출하며, 파이프를 통해 전달될 때 JSON을 방출하고 jam agent-context를 통해 기계가 읽을 수 있는 명령어 스키마를 게시합니다.

Jam 웹훅은 jam.created와 recording_link.created 이벤트를 귀하의 HTTPS 엔드포인트로 푸시하며, Svix를 통해 표준 웹훅 형식으로 서명됩니다. CLI는 Jam 백엔드와 통신하지만, 그 백엔드는 직접 구축할 수 있는 계약(contract)으로 문서화되어 있지 않습니다. CLI를 API로 취급하십시오.

에이전트에게 중요한 부분별 비교

아래 네 가지 차원은 이 시리즈 전체에서 고정적입니다. Jam의 경우, 격차는 특이한 방향으로 나타납니다. MCP 서버가 더 넓은 표면(broader surface)이며, 직접적인 경로는 생성 및 이벤트 주변의 특정 구멍들을 채웁니다.

에이전트가 Jams를 읽을 때 실제로 할 수 있는 것들

Jams를 읽는 것에 대해서는 두 표면이 거의 동등합니다. MCP가 비디오 이해(video understanding) 측면에서 앞서 나갑니다.

에이전트가 쓰기, 생성, 반응할 때 할 수 있는 것들

실제 격차는 쓰기(write) 쪽에 있습니다. MCP는 기존 Jams를 관리할 수 있지만, 직접적인 경로는 하나를 생성하거나 하나가 나타날 때 반응할 수만 있습니다.

MCP 표면이 보이는 것보다 얇은 곳들

운영 환경에서는 데모와 달리 세 가지 제약 사항이 나타납니다. 비디오 도구(analyzeVideo, getVideoTranscript, getVideoChapters, getFrames)와 getScreenshots는 Instant Replay Jam에는 사용할 수 없습니다. 특히 getFrames는 Cloudflare Stream에 호스팅된 비디오 Jam에서만 작동합니다. 또한, Jam은 하나의 Jam을 한 번에 에이전트에 제공하는 것을 권장하는데, 이는 단일 Jam의 로그 및 네트워크 페이로드가 컨텍스트 창을 소진시킬 수 있기 때문입니다.

검토할 데이터 경로도 있습니다. Jam에 따르면 일부 MCP 도구는 Google의 Gemini를 사용하며, 이때 학습은 제외되고 데이터는 비식별화됩니다. 규제 대상 고객에게 있어 이는 출시 후에가 아니라 보안 설문지(security questionnaire)에서 다루어져야 할 문제입니다.

각 방식이 안내하는 인증 경로

Jam MCP는 두 가지 유형의 자격 증명(credential)을 허용합니다. 브라우저 OAuth는 Claude, ChatGPT 및 IDE 클라이언트의 기본값입니다. 사용자가 로그인하고 작업 공간을 선택하며, 클라이언트가 토큰을 보유합니다. PAT(Personal Access Token)는 브라우저 단계를 완전히 건너뛰고 Authorization: Bearer jam_pat_... 형태로 전송됩니다.

CLI도 동일하게 두 가지를 허용합니다. jam auth login은 OAuth를 실행하고 접근 및 새로 고침 토큰을 ~/.config/jam/credentials.json에 0600 권한으로 저장합니다. 또는 PAT를 jam auth login --token으로 파이프하거나 JAM_TOKEN으로 설정할 수 있습니다. 웹훅(Webhooks)은 세 번째 자격 증명인, 엔드포인트별 whsec_ 서명 비밀(signing secret)을 사용하며, 이는 svix-id, svix-timestamp, 그리고 본문(body)에 대한 HMAC-SHA256으로 검증됩니다.

PAT가 해결하는 것은 다중 테넌트 환경이 아닌 헤드리스 환경입니다

PAT는 헤드리스(headless) 방식의 해답이며, Jam은 이를 신중하게 설계했습니다. 각 토큰은 하나의 작업 공간에 범위가 지정되며, 한 사용자에게 연결되고, mcp:read, mcp:write 중 하나를 포함하며, 7일, 30일, 90일 또는 1년의 필수 만료 기간을 가집니다. Jam은 해시(hash)만 저장하므로 평문(plaintext)은 한 번만 표시됩니다.

해당 디자인은 개발자의 Cursor 설정에 적합합니다. 하지만 B2B 제품에는 어색합니다. 모든 고객 사용자가 Jam 설정에서 토큰을 발급받아 앱에 붙여넣고, 만료될 때마다 이 과정을 반복해야 합니다. 두 경로 모두 멀티테넌트 B2B 에이전트에서 사용자별 자격 증명 격리(per-user credential isolation)를 필요로 합니다. 어느 경우에도 해당 경로는 저장, 로테이션 또는 취소 문제를 해결하지 못합니다. 이는 어떤 경로를 선택하든 인프라스트럭처 문제입니다.

Jam MCP가 대신 관리하는 것

MCP를 사용하면 Jam이 툴 스키마(tool schemas), 필터링 로직, 그리고 비디오 분석 파이프라인을 소유하게 됩니다. 이것이 진정한 레버리지입니다. getNetworkRequests는 이미 상태 코드, 호스트, 메서드 및 콘텐츠 유형별로 필터링하므로, 실패한 요청 몇 개와 페이지가 만든 모든 요청을 컨텍스트에 담아낼 수 있게 해줍니다.

여전히 사용자가 소유해야 할 부분은 토큰 저장, 새로고침(refresh), 그리고 설정 > MCP에서 사용자가 접근 권한을 취소하는 순간을 처리하는 것입니다. 또한 이 기능은 Jam의 일정에 따라 업데이트됩니다. Jam의 문서에는 오늘날 33개의 툴이 나열되어 있는 반면, Scalekit의 Jam 커넥터 카탈로그에는 15개만 있어, 서버 측 툴 세트가 얼마나 빠르게 성장했는지 보여주는 격차입니다. Jam은 MCP 툴 스키마에 대한 버전 관리 체계를 발표하지 않으므로, 하드코딩하기보다는 실행마다 툴을 재목록화(re-list)해야 합니다.

CLI와 웹훅이 남기는 것

CLI 경로는 에이전트 런타임에서 바이너리(binary)를 소유한다는 것을 의미합니다. 프로세스 생성(process spawning), JSON 파싱, 종료 코드(종료 코드 3은 인증 실패, 7은 HTTP 429), 페이지당 최대 500개로 제한된 커서 페이징(cursor pagination), 그리고 jam upgrade --target을 사용한 버전 고정(version pinning) 등이 포함됩니다. CI에서 JAM_SKIP_UPDATE_CHECK=1을 설정하여 고정된 바이너리가 계속 고정되도록 하세요.

웹훅은 공개 HTTPS 엔드포인트, 시그니처 검증(signature verification), 그리고 svix-id를 키로 하는 Idempotency를 추가합니다. Jam은 즉시 시작하여 10시간 간격으로 백오프하는 고정된 스케줄에 따라 실패한 전송을 재시도하므로, 재전달(redelivery)을 염두에 두고 설계해야 합니다. 처리 후 시간 초과가 발생한 소비자(consumer)는 동일한 svix-id를 다시 볼 것입니다.

Jam MCP가 적절한 경로일 때

• 엔지니어는 Jam 링크를 Claude Code, Cursor 또는 VS Code에 붙여넣고, 에이전트가 콘솔, 네트워크 및 사용자 이벤트가 이미 컨텍스트로 존재하는 상태에서 버그부터 수정까지 진행하기를 원합니다.
• 지원 또는 제품 에이전트는 고객의 Jam 배치를 처리하고 Linear 또는 Jira에 티켓을 그룹화합니다.
• 에이전트는 비디오 이해 능력이 필요합니다: 추출된 사용자 의도, 스크립트, 챕터 또는 특정 타임스탬프에서의 프레임입니다.
• 에이전트는 모든 커넥터에서 하나의 프로토콜을 유지하여 도구 검색(tool discovery)을 통일하는 MCP 도구와 함께 Jam을 오케스트레이션합니다.

CLI 및 웹훅이 승리할 때

• 트리아지 에이전트는 jam.created를 사용하여 Jam이 생성되는 순간부터 폴링 없이 시작해야 합니다.
• 코딩 에이전트는 작동하는 흐름을 새로운 Jam으로 기록하고 해당 링크를 풀 리퀘스트에 첨부하여 수정 사항을 입증해야 합니다.
• CI는 실패한 Playwright 테스트와 그 trace.zip 파일을 콘솔 및 네트워크 이벤트가 비디오에 동기화된 Jam으로 변환합니다.
• 에이전트는 샌드박스에서 실행되며, MCP 세션을 유지하는 것보다 고정된 바이너리로 셸링 아웃(shelling out)하는 것이 더 간단합니다.

두 경로 모두에 존재하는 자격 증명 문제

어떤 경로를 선택하든, 멀티테넌트 Jam 에이전트는 사용자당 하나의 Jam 자격 증명을 보유합니다. 1,800명의 연결된 사용자가 있는 200개의 고객 워크스페이스는 1,800개의 자격 증명 생애주기를 의미합니다.

토큰 만료, 취소, 그리고 조용한 실패

MCP 흐름의 OAuth 토큰은 새로 고침이 필요합니다. PAT(Personal Access Token)는 아예 새로 고침할 수 없는 하드 만료 기한에 도달하며, 사용자는 새 토큰을 발급받아야 합니다. 모든 사용자는 Settings > MCP에서 MCP 클라이언트 또는 PAT를 취소할 수 있으며, 다음 도구 호출이 실패합니다. 연결 상태를 실행 전에 확인하지 않는 에이전트는 작업 중간에 문제를 발견하게 되며, 이는 보통 조용히 발생한 트리아지(triage)로 간주됩니다.

각 토큰은 또한 어딘가에 보관되어야 합니다: 저장 시 암호화되고, 테넌트별로 격리되며, 기록되지 않고, LLM 컨텍스트에도 포함되어서는 안 됩니다. 두 Jam 경로 모두 이를 제공하지 못합니다.

Scalekit이 적합한 이유

Scalekit의 Jam MCP 커넥터는 OAuth 플로우, 토큰 저장 및 새로고침을 처리하므로 자격 증명이 에이전트 런타임에 절대 노출되지 않습니다. 사용자는 브라우저에서 한 번만 승인하며, 이후 모든 실행(백그라운드 실행 포함)은 해당 사용자의 볼트된 토큰을 서버 측에서 해결합니다. 명확하게 언급된 한 가지 주의사항이 있습니다: Scalekit은 MCP 경로를 처리합니다. 만약 기록을 위해 CI에서 Jam CLI도 실행한다면, 그 PAT는 여전히 관리해야 하는 사용자 소유입니다.

Scalekit을 통해 에이전트에 Jam 연결하기

Scalekit은 하나의 커넥터인 Jam MCP (jammcp)를 통해 Jam에 노출하며, 이는 툴 호출을 Jam 자체의 MCP 서버로 라우팅합니다. 별도의 Jam API 커넥터는 없으며, 이는 Jam 자체의 인터페이스와 일치합니다. 예제는 Python을 사용합니다: 직접적인 툴 호출을 위한 Anthropic SDK, 그리고 가상 MCP 서버를 통한 LangChain입니다.

필수 조건

• Developers > API Credentials에서 가져온 Scalekit 자격 증명: SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, SCALEKIT_CLIENT_SECRET
• AgentKit > Connections 아래에 생성된 Jam MCP 연결. 코드의 connection_name은 대시보드 이름과 정확히 일치해야 합니다. 불일치는 가장 흔한 통합 오류이며, 인증 실패가 아닌 누락된 툴로 나타납니다.
• 패키지: pip install scalekit-sdk-python anthropic python-dotenv

사용자 한 번 승인하기

연결된 계정은 Jam 연결의 사용자별 인스턴스입니다. 상태를 확인하고, 활성화되어 있지 않다면 사용자에게 인증 링크를 보내며, 여전히 그렇지 않다면 실패 처리(fail closed)합니다. 프로덕션 앱은 자체 UI에 이 링크를 노출합니다.

import os

from dotenv import load_dotenv
...

이 사용자가 호출할 수 있는 툴 검색하기

list_scoped_tools는 평면화된 커넥터 카탈로그를 반환하지 않습니다. 현재 사용자의 연결된 계정이 호출하도록 승인된 툴을 반환합니다. 그런 다음 코드는 그 인터페이스를 트리아지 역할이 필요로 하는 다섯 가지 툴로 좁히는데, 이는 툴 과부하(tool bloat)에 대한 해결책이 더 나은 프롬프팅이 아니라 인터페이스 축소이기 때문입니다.

from google.protobuf.json_format import MessageToDict

TRIAGE_TOOLS = {
...

Claude 툴 사용 루프 실행하기

모든 도구 호출은 execute_tool을 통해 이루어지며, 이 함수가 Scalekit 내부의 사용자의 Jam 토큰을 해결합니다. 에이전트는 자격 증명(credentials)이 아닌 도구 결과만 확인합니다. 루프는 Claude가 더 이상 도구를 요청하지 않을 때까지 계속됩니다.

import anthropic

client = anthropic.Anthropic()
...

가상 MCP 서버를 사용한 멀티-도구 Jam 에이전트

Jam 에이전트는 거의 Jam에서 멈추지 않습니다. 분류(Triage)는 Linear, Jira 또는 GitHub로 이어집니다. 가상 MCP 서버는 해당 에이전트에게 각 연결에서 허용하는 도구만 노출하고, 사용자별 실행당 단기 세션 토큰을 제공하는 단일 엔드포인트를 제공합니다. 배포하거나 호스팅하거나 유지 관리할 MCP 서버가 필요하지 않습니다.

에이전트 역할별로 서버를 한 번 정의하기

사용자별로 여러 번 만드는 것이 아니라, 서버 자체를 한 번 만듭니다. 응답에는 모든 사용자 및 모든 실행에서 재사용되는 정적 mcp_server_url이 포함됩니다. 이 설정은 네 개의 읽기 전용 Jam 도구와 세 개의 Linear 도구를 쌍으로 묶습니다. 두 연결 이름 모두 AgentKit > Connections에 존재해야 합니다.

from scalekit.actions.models.mcp_config import McpConfigConnectionToolMapping

vmcp_response = actions.mcp.create_config(
...

연결 확인 및 세션 토큰 발급하기

각 실행 전에, 사용자의 Jam 및 Linear 계정이 여전히 활성화되어 있는지 확인하고 해당 사용자에게 범위가 지정된(scoped) 토큰을 발급합니다. 만료 시간은 예상되는 실행 시간을 초과하도록 설정해야 합니다. Node.js SDK는 아직 세션 토큰을 발급하지 않으므로, 이 단계는 Python 백엔드에서 처리하는 것이 좋습니다.

from datetime import timedelta

accounts_response = actions.mcp.list_mcp_connected_accounts(
...