MCP로 Claude를 프로젝트 관리 도구에 연결하는 방법

MCP란 무엇인가

Model Context Protocol(MCP)은 AI 어시스턴트가 다른 애플리케이션의 도구를 호출할 수 있게 해 주는 개방형 표준입니다. MCP 서버를 운영하는 프로젝트 관리 도구는 "내 이슈 목록 보기"나 "이슈 만들기" 같은 도구 목록을 공개하고, Claude Code 같은 클라이언트는 사용자가 허락한 권한 안에서 그 도구를 대신 호출합니다.

실제로는 세 가지를 의미합니다. 어시스턴트는 사용자가 붙여 넣은 내용이 아니라 실제 보드를 기준으로 일합니다. 제안만 하는 것이 아니라 직접 실행할 수 있습니다. 그리고 모든 동작은 도구 자체의 권한 검사를 거치므로, 사용자가 직접 할 수 있는 일만 할 수 있습니다.

시작하기 전에 필요한 것

• 해당 도구의 계정. Atrix라면 워크스페이스가 필요합니다. 무료 플랜은 없습니다. 모든 워크스페이스는 카드 등록이 필요한 7일 Builder 체험으로 시작하며, MCP 서버는 모든 플랜에 포함되어 있습니다.
• 서버 주소. Atrix의 주소는 https://atrix.dev/api/mcp이며 Streamable HTTP로 제공됩니다.
• 클라이언트. Claude Code, 웹이나 데스크톱의 Claude, Cursor, 또는 HTTP로 MCP를 지원하는 다른 클라이언트.

아래의 어떤 클라이언트도 API 키를 따로 만들 필요가 없습니다. 모두 브라우저에서 OAuth로 로그인합니다.

Claude Code 연결하기

같은 세션에서 코드와 보드를 함께 읽는 어시스턴트가 필요하다면 Claude Code가 가장 잘 맞습니다.

1. 서버를 추가합니다. 명령어에는 자격 증명이 들어가지 않습니다.

   claude mcp add --transport http atrix https://atrix.dev/api/mcp
   

2. Claude Code를 실행하고 /mcp를 입력한 뒤 atrix를 선택하고 Authenticate를 고릅니다.

3. 브라우저 창이 열립니다. 로그인하고 워크스페이스를 고른 뒤 스코프를 승인합니다. 첫 연결은 읽기 권한만 요청합니다.

4. 터미널로 돌아와 제대로 연결되었는지 확인합니다.

   Who am I connected to Atrix as, and what can you do?
   

   Claude는 atrix_whoami를 호출합니다. 이 도구는 연결된 사람, 워크스페이스, 연결이 가진 스코프, 그리고 사용할 수 있는 도구를 알려 줍니다.

CI나 브라우저가 없는 서버에서는 대신 개인 토큰을 넘길 수 있습니다. Atrix의 Settings → Atrix Tokens에서 토큰을 만들고 환경 변수에 보관하세요.

claude mcp add --transport http atrix https://atrix.dev/api/mcp \
  --header "Authorization: Bearer $ATRIX_TOKEN"

노트북에서는 브라우저 로그인을 권합니다. 디스크에 남겨 둘 것이라면 오래 유지되는 키보다 갱신과 폐기가 가능한 OAuth 토큰이 훨씬 낫습니다.

Claude와 Claude Desktop 연결하기

웹의 Claude와 Claude Desktop은 커스텀 커넥터를 사용합니다.

1. Settings → Connectors → Add custom connector(사용자 지정 커넥터 추가)를 엽니다.

2. 이름을 정하고 엔드포인트를 붙여 넣습니다.

   https://atrix.dev/api/mcp
   

3. Connect를 선택하고, 열리는 창에서 Atrix에 로그인합니다.

Claude가 서버에 스스로를 등록하므로 클라이언트 ID나 시크릿을 만들 필요가 없습니다. 회사용 Claude 플랜을 쓰고 있다면, 커넥터를 추가하기 전에 관리자가 커스텀 커넥터를 허용해야 할 수도 있습니다.

Cursor 연결하기

Cursor를 비롯해 Streamable HTTP를 지원하는 대부분의 클라이언트는 같은 JSON을 사용합니다. 프로젝트의 .cursor/mcp.json에 넣거나, 어디서든 쓰려면 ~/.cursor/mcp.json에 넣으세요.

{
  "mcpServers": {
    "atrix": { "url": "https://atrix.dev/api/mcp" }
  }
}

처음 도구가 호출될 때 Cursor가 로그인용 브라우저를 엽니다. 토큰을 쓰려면 다음과 같이 설정합니다.

{
  "mcpServers": {
    "atrix": {
      "url": "https://atrix.dev/api/mcp",
      "headers": { "Authorization": "Bearer atx_pat_…" }
    }
  }
}

연결 후 권한은 어떻게 작동하는가

첫 연결은 일부러 읽기 전용입니다. Claude가 무언가를 바꾸기 전에, 먼저 보드를 어떻게 다루는지 확인할 수 있습니다.

이슈 생성처럼 쓰기가 필요한 요청을 하면 서버는 403 insufficient_scope로 응답하며 부족한 스코프를 알려 줍니다. 제대로 구현된 클라이언트는 브라우저를 다시 열어 정확히 그 스코프만 승인하게 합니다. 클라이언트가 그렇게 하지 않는다면 다시 인증(Claude Code에서는 /mcp)하고 거기서 추가 스코프를 승인하세요.

모든 연결에는 몇 가지 규칙이 적용됩니다.

• 스코프는 권한을 좁힐 뿐, 넓히지 않습니다. 연결은 그것을 승인한 사람보다 더 많은 일을 할 수 없습니다. crm.value를 부여해도, 볼 권한이 없는 사람에게는 거래 금액이 보이지 않습니다.
• 권한은 호출할 때마다 확인합니다. 누군가 워크스페이스에서 접근 권한을 잃으면, 그 사람이 만든 모든 연결도 같은 순간에 권한을 잃습니다.
• 한도는 연결마다 적용됩니다. 분당 호출 120회, 쓰기 30회입니다. 이를 넘으면 서버가 Retry-After 헤더와 함께 429로 응답합니다.
• 모든 호출은 감사 기록에 남습니다. 도구, 스코프, 결과를 ID로만 기록하며 내용은 절대 남기지 않습니다.
• 급여 정보에는 절대 접근할 수 없습니다. 어떤 스코프도 급여에 닿지 않습니다.

실제로 통하는 프롬프트

아래 프롬프트는 Atrix 서버가 제공하는 도구에 그대로 대응합니다. 도구 이름을 직접 말할 필요는 없습니다. Claude가 알아서 고릅니다. 승인 요청에서 무엇이 나올지 알 수 있도록 도구 이름을 함께 적었습니다.

하루 시작하기

• "What's overdue for me this week?"(이번 주에 내가 놓친 일은?)는 attention_today를 사용합니다. 기한이 지났거나 이번 주가 기한인 업무, 읽지 않은 멘션, 오늘의 회의를 돌려줍니다.
• "Website 제품은 어떻게 되고 있어? 막혀 있는 건 뭐야?"는 project_status를 사용합니다. 완료율, 상태별 업무, 그리고 일주일 넘게 리뷰나 진행 중에 머물러 있는 항목을 보여 줍니다.

찾고 읽기

• "가격 정책 스펙을 찾아서 열린 질문을 요약해 줘."는 search 다음에 fetch를 사용합니다. 검색은 제목뿐 아니라 페이지 본문까지 찾습니다.
• "Zara에게 할당된 것 중 리뷰 중인 걸 모두 보여 줘."는 people_find와 work_list_issues를 사용합니다.

업무 만들고 바꾸기 (work.write 필요)

• "Website에 이슈를 만들어 줘: '푸터의 깨진 가격 링크 수정', 우선순위 높음, 금요일까지, 나에게 할당."은 work_create_issue를 사용하고, 이어서 work_schedule_issue와 work_assign_issue를 사용합니다.
• "결제 관련 버그 세 개를 In review로 옮기고, 수정본이 스테이징에 올라갔다고 댓글을 달아 줘."는 work_bulk_update와 work_comment_issue를 사용합니다.

코드에서 보드로 (Claude Code)

• "src/billing의 TODO 주석을 읽고 TODO마다 Website에 태스크를 하나씩 만들어 줘. 중복은 만들지 마."라고 하면 Claude는 파일을 로컬에서 읽고 ifNotExists를 붙여 work_create_issue를 호출합니다. 같은 제목의 열린 이슈가 이미 있으면 새로 만들지 않고 그 이슈를 돌려줍니다.

서버가 의도적으로 거부하는 일이 하나 있습니다. 어시스턴트는 에픽을 만들 수 없습니다. 에픽은 업무의 큰 틀을 정하는 것이므로, Claude는 스토리, 태스크, 버그를 만들고 그 상위 항목을 지정합니다.

어떤 프로젝트 관리 MCP 서버든 확인할 것

Atrix는 여러 선택지 중 하나일 뿐입니다. 어떤 도구를 연결하든, 어시스턴트에게 쓰기 권한을 주기 전에 다음을 확인하세요.

1. OAuth인가, API 키인가. OAuth라면 동의 화면에서 직접 승인한 스코프 단위 토큰이며, 다른 것을 교체하지 않고도 폐기할 수 있습니다. 붙여 넣는 API 키는 계정이 할 수 있는 모든 일을 담고 있는 경우가 많고, 설정 파일 안에 그대로 남습니다.
2. 스코프. 쓰기 없이 읽기만 부여할 수 있나요? 프로젝트, 고객, 사람 데이터를 나눌 수 있나요? 선택지가 "전부"뿐이라면 그 연결은 비밀번호처럼 다루세요.
3. 쓰기 승인. 클라이언트가 쓰기마다 확인을 받나요? 서버는 어떤 도구가 읽기 전용인지 표시하나요? 요청을 잘못 이해한 모델은 데이터가 아니라 확인 단계에서 멈춰야 합니다.
4. 감사 기록. 연결이 무엇을 언제 했는지 볼 수 있나요? "이 이슈 스무 개를 누가 닫았지?"라는 질문에 답하는 방법이 바로 도구 호출 로그입니다.
5. 사용량 한도. 폭주하는 루프는 백로그 끝이 아니라 한도에서 멈춰야 합니다.
6. 모델이 읽는 내용. 티켓 본문과 댓글은 모델이 읽습니다. 누군가 티켓에 지시문을 적어 둘 수도 있으니, 중요한 작업에는 쓰기 승인을 켜 두세요.

문제가 생겼을 때

• 401: 로그인이 만료되었거나 폐기되었습니다. /mcp를 실행해 다시 인증하세요.
• 403 insufficient_scope: 연결에 스코프가 부족합니다. 브라우저가 열리면 승인하거나, 해당 스코프를 포함해 다시 연결하세요.
• 스코프 이름이 없는 403: 스코프는 있지만 워크스페이스에서 계정에 권한이 없습니다. 워크스페이스 관리자에게 문의하세요.
• 429: Retry-After에 적힌 초만큼 기다리세요. 짧은 간격으로 재시도하면 대기 시간만 늘어납니다.

자주 묻는 질문

Claude를 Atrix에 무료로 연결할 방법이 있나요?

없습니다. Atrix에는 무료 플랜이 없습니다. 모든 워크스페이스는 카드 등록이 필요한 7일 Builder 체험으로 시작하며, MCP 서버는 첫날부터 포함됩니다. Builder는 월 $39에 5석, Studio는 월 $149에 15석이며, 연간 플랜은 20% 할인됩니다.

Claude가 묻지 않고 보드를 바꿀 수 있나요?

첫 연결은 읽기 전용이므로 그럴 수 없습니다. 쓰기에는 브라우저에서 승인한 스코프가 필요하며, Claude Code 같은 클라이언트는 따로 설정하지 않는 한 도구를 실행하기 전에 먼저 묻습니다.

Atrix가 Claude와 나눈 대화를 볼 수 있나요?

아니요. 서버가 보는 것은 Claude가 보내는 도구 호출뿐입니다. 예를 들어 검색어나 새로 만드는 이슈의 필드 같은 것입니다. 감사 기록에는 내용이 아니라 ID만 남습니다.

어떤 클라이언트를 써야 하나요?

TODO나 실패한 테스트를 이슈로 만드는 것처럼 업무가 코드에서 시작된다면 Claude Code를 쓰세요. 계획, 진행 상황 질문, 글쓰기에는 Claude나 Claude Desktop이 좋습니다. 이미 Cursor에서 일하고 있다면 Cursor를 쓰면 됩니다. 세 가지 모두 같은 도구에 같은 한도로 접근합니다.

연결은 어떻게 해제하나요?

클라이언트에서 서버를 제거하고(Claude Code에서는 claude mcp remove atrix), Atrix 설정에서 연결을 폐기하세요. Atrix에서 폐기하면 다음 요청부터 바로 작동이 멈춥니다.

내 보드에서 직접 해 보기

요금제에서 워크스페이스를 시작하고, 위 단계대로 Claude를 연결한 뒤 기한이 지난 일을 물어보세요. MCP 서버 가이드에는 모든 클라이언트의 설정 방법이 있고, 도구 레퍼런스에는 모든 도구의 스코프와 입력값이 정리되어 있습니다. 전체 개요는 Claude와 Atrix와 MCP 기능 페이지에서 확인하세요.