Umtri MCP를 Claude Code에 연결하기

지난 편에서 Umtri가 프로젝트 구조를 트리로 기록·시각화하는 서비스라는 걸 알아봤습니다. 이번 편에서는 Umtri와 Claude Code를 실제로 연결하는 방법을 다룹니다.

연결에 사용하는 기술이 MCP(Model Context Protocol)입니다. MCP 자체의 개념은 바이브코딩 6편에서 다뤘으니, 여기서는 Umtri를 연결하는 실전 과정에 집중합니다. 설정은 터미널에서 명령어 한 줄이면 끝납니다.

Umtri를 연결하면 무엇이 달라지나

MCP 없이 AI는 대화 내용과 열린 파일 안에서만 정보를 얻습니다. Umtri MCP를 연결하면 Claude Code가 Umtri에 있는 프로젝트 구조를 직접 읽고, 노드를 추가하거나 수정하는 작업을 자동으로 수행할 수 있습니다.

구분	MCP 없을 때	Umtri MCP 있을 때
AI가 알 수 있는 것	대화 내용, 열린 파일	Umtri 트리 구조까지 포함
작업 방식	코드만 작성	트리 조회·노드 추가·수정 가능
예시	”이 함수 고쳐줘"	"Umtri에서 트리 불러온 다음 이 기능 노드 추가해줘”

시작 전 준비: Umtri 계정과 토큰 발급

MCP를 연결하려면 먼저 Umtri 계정이 있어야 합니다.

1. Umtri 가입 및 로그인

app.umtri.io에서 계정을 만들고 로그인합니다.

2. 프로젝트(그라운드) 만들기

로그인 후 “New Ground” 버튼을 눌러 새 프로젝트를 만듭니다. 이름은 만들고 있는 프로젝트 이름으로 설정합니다. (예: bookmark-app)

3. API 토큰 발급

사이드바 설정(톱니 아이콘)에서 API Tokens로 들어가, 라벨(예: claude-code)을 입력하고 스코프를 고른 뒤 Generate token을 누릅니다. 이 토큰은 Claude Code가 Umtri에 접근할 수 있는 열쇠입니다.

스코프는 두 가지입니다.

스코프	가능한 작업	선택 기준
`read`	그라운드 목록, 그래프·영향 조회, 버그·시즌 목록	기본값. 어떤 클라이언트에도 안전합니다
`write`	위 작업 + 노드 생성·수정·삭제	AI가 트리를 직접 고치게 할 때

이 시리즈에서는 Claude Code가 트리에 기록까지 남기게 할 것이므로 write를 고릅니다.

발급된 토큰은 umtri_pat_으로 시작합니다. 한 번만 표시되고 이후에는 복구할 수 없으니(서버에는 해시만 저장됩니다) 바로 안전한 곳에 복사해 두세요. 잃어버렸다면 같은 페이지에서 폐기하고 새로 발급하면 됩니다.

Claude Code에 Umtri MCP 연결하기

Umtri는 MCP 서버를 https://mcp.umtri.io에서 직접 호스팅합니다. 그래서 저장소를 clone하거나 뭔가를 설치할 필요 없이, 이 주소를 가리키고 토큰으로 인증하기만 하면 됩니다.

터미널에서 아래 명령어를 실행합니다. 뒤쪽 토큰 부분을 방금 발급받은 값으로 바꿉니다.

claude mcp add --transport http umtri https://mcp.umtri.io \
  --header "Authorization: Bearer umtri_pat_xxxxxxxxxxxxxxxx"

명령어를 실행하면 Claude Code가 Umtri MCP 서버를 등록합니다. 뒤에 --scope user를 붙이면 모든 프로젝트에서, --scope local을 붙이면 현재 프로젝트에서만 쓸 수 있게 등록됩니다.

연결 확인

먼저 터미널에서 등록 상태를 봅니다.

claude mcp list

umtri: ✓ Connected가 보이면 정상입니다. Claude Code 세션 안에서 /mcp를 입력하면 실제로 쓸 수 있는 도구 목록도 볼 수 있습니다.

대화로 확인해도 됩니다.

내 Umtri 프로젝트 목록 보여줘

연결이 정상이라면 Umtri에 만들어둔 그라운드 목록이 나타납니다.

한 가지 주의할 점 — 토큰은 등록 시점에 검증되지 않고 그대로 저장됩니다. 그래서 토큰이 틀려도 연결 자체는 성공한 것처럼 보이고, 실제 호출만 전부 실패합니다. 도구가 안 보이거나 호출이 계속 실패하면 토큰과 스코프부터 다시 확인하세요.

Umtri MCP로 할 수 있는 것들

MCP 연결 후 Claude Code가 사용할 수 있는 주요 기능입니다.

명령	설명
`list_projects`	Umtri에 있는 프로젝트 목록 조회
`get_graph`	특정 프로젝트의 트리 구조 전체 조회
`create_node`	트리에 새 노드(trunk/limb/twig/leaf/vein) 추가
`update_node`	기존 노드 이름이나 위치 수정
`delete_node`	노드 삭제
`record_commit`	커밋 정보를 Umtri 타임라인에 기록
`create_bug`	버그 이슈를 Umtri에 등록
`list_bugs`	등록된 버그 목록 조회

실제 사용 예시

MCP가 연결된 상태에서 Claude Code와 이렇게 대화할 수 있습니다.

현재 구조 파악

bookmark-app 그라운드의 트리 구조를 가져와서 현재 어떤 컴포넌트들이 있는지 정리해줘

Claude Code가 Umtri에서 트리를 읽어와 현재 구조를 설명합니다.

기능 추가와 동시에 구조 기록

BookmarkList 컴포넌트에 검색 기능을 추가해줘.
추가 후에는 Umtri 트리에도 SearchBar 컴포넌트를 leaf 노드로 등록해줘.

코드 작성과 구조 기록을 한 번의 요청으로 처리합니다.

구조 기반으로 AI에게 맥락 제공

Umtri에서 현재 트리 구조 읽어오고, 태그 필터 기능을 어디에 추가하면 좋을지 제안해줘.

AI가 현재 프로젝트 구조를 파악한 뒤 아키텍처 관점에서 의견을 냅니다.

주의사항: 토큰 관리

API 토큰은 Umtri 계정에 대한 접근 권한을 가집니다. 위 방식으로 등록하면 토큰은 Claude Code의 설정 파일에 저장되므로, 프로젝트 코드나 .mcp.json처럼 git에 올라가는 파일에 토큰을 직접 적어 넣지 마세요. GitHub에 그대로 공개될 수 있습니다.

토큰을 파일에 남기지 않고 환경 변수로만 다루고 싶다면, 호스팅 서버 대신 MCP 서버를 로컬에서 실행하는 방법이 있습니다. umtri-mcp 패키지를 stdio로 띄우고 토큰은 환경 변수로 넘기는 방식입니다.

claude mcp add umtri \
  -e UMTRI_API_TOKEN=umtri_pat_xxxxxxxxxxxxxxxx \
  --transport stdio \
  -- npx -y umtri-mcp

npx -y라서 미리 설치할 필요는 없고, 버전을 고정하거나 API를 자체 호스팅할 때도 이 방식을 씁니다. 다만 대부분의 경우에는 앞서 소개한 호스팅 HTTP 방식이 더 간단합니다.

토큰이 노출됐다고 판단되면 설정의 API Tokens 페이지에서 해당 토큰을 폐기하고 새로 발급하면 됩니다.

MCP 연결로 달라지는 것

MCP를 연결하기 전과 후의 차이를 정리하면 이렇습니다.

구분	MCP 연결 전	MCP 연결 후
구조 기록	수동으로 직접 Umtri에 입력	Claude Code가 요청하면 자동으로 기록
프로젝트 파악	코드 파일 직접 열어서 확인	Umtri 트리 한 번 조회로 전체 파악
AI 맥락 제공	매번 대화에서 구조 설명	Umtri 트리를 불러와 바로 맥락 제공

다음 편부터는 MCP 연결이 된 상태에서 실제로 기능을 쌓아가며 트리에 기록을 남기는 흐름을 다룹니다.