Agentation ↔ Cursor / Claude Code 연동 정리

Shin Jinseop·2026년 3월 9일

프로젝트 Agentation을 Cursor(및 Claude Code)와 연동할 때 설정한 내용과 사용 방법을 정리한 문서입니다.

1. 연동 개요

1.1 역할 구분

구분설명
agentation (npm 패키지)앱 안에 들어가는 툴바 UI. 브라우저에서 요소 선택 후 코멘트를 남기면 서버(4747)로 전송
agentation-mcp (npm 패키지)MCP 서버. HTTP(4747) + stdio 동시 제공. 툴바가 보낸 어노테이션을 저장하고, Cursor/Claude가 MCP로 조회·처리
Cursor / Claude CodeMCP 클라이언트. agentation_get_all_pending 등 도구를 호출해 어노테이션을 가져오고, 수정 후 resolve 등으로 처리

1.2 데이터 흐름

[앱 화면 + Agentation 툴바]  →  POST http://localhost:4747  →  [agentation-mcp 서버]
                                                                        ↑
[Cursor / Claude Code]  ←——  MCP (stdio)  ←——  같은 프로세스
  • 툴바와 에이전트가 같은 agentation-mcp 프로세스를 써야 어노테이션이 보입니다.
  • 터미널에서 서버를 따로 띄우면 그 프로세스에 저장되고, Cursor가 MCP 호출 시 다른 프로세스를 띄울 수 있어서 데이터가 안 보일 수 있음.

1.3 어노테이션 → Webhook → 외부 서비스 플로우

어노테이션 → Webhook → 외부 서비스 플로우

2. 이 프로젝트에서 한 설정

2.1 설치한 패키지

위치패키지용도
프로젝트 루트agentation-mcpMCP 서버 실행 (npx agentation-mcp server)
appsagentation (devDependency)앱에 툴바 컴포넌트 넣기
  • 루트: package.json 에 "agentation-mcp": "^1.2.0" (또는 -w 로 설치)
  • client: package.json devDependencies 에 "agentation": "^2.0.0"

2.2 앱에 툴바 넣기 (client)

파일: src/pages/_app.tsx

  • 개발 모드에서만 <Agentation /> 렌더.
  • Next.js dynamic import, ssr: false (클라이언트 전용).
  • 서버 URL 명시: endpoint="http://localhost:4747" (같은 서버로 보내기 위해).
const Agentation = process.env.NODE_ENV === 'development'
  ? dynamic(() => import('agentation').then((m) => m.Agentation), { ssr: false })
  : () => null;

// ...
{process.env.NODE_ENV === 'development' && <Agentation endpoint="http://localhost:4747" />}

2.3 MCP 설정 (Cursor / Claude Code)

중요: 글로벌과 프로젝트 둘 다에 같은 서버 이름을 넣으면 충돌할 수 있으므로, 한쪽에만 두는 것을 권장했습니다.

Cursor – 글로벌 설정 (권장)

파일: ~/.cursor/mcp.json

{
  "mcpServers": {
    "agentation": {
      "command": "npx",
      "args": ["-y", "agentation-mcp", "server"]
    }
  }
}
  • Cursor는 이 설정을 읽어서 Cursor가 npx -y agentation-mcp server 를 실행합니다.
  • 실행 시 현재 워크스페이스(프로젝트 루트) 기준으로 npx가 동작하므로, 프로젝트에 설치된 agentation-mcp가 사용됩니다.

Cursor – 프로젝트 설정 (선택)

파일: 프로젝트/.cursor/mcp.json

  • 같은 내용을 넣을 수 있지만, 글로벌과 동시에 agentation을 넣지 말 것.
  • 충돌을 피하려고 이 프로젝트에서는 .cursor/mcp.json 의 agentation 항목을 비워 두었습니다 ("mcpServers": {}).

Claude Code

  • doctor 안내대로: claude mcp add agentation -- npx agentation-mcp server
  • Cursor 사용 시에는 이 단계는 선택입니다.

3. 서버 실행 방법

3.1 Cursor가 띄우는 경우 (일반 사용)

  • MCP 설정에 agentation이 있으면, Cursor가 채팅에서 Agentation 도구를 처음 쓸 때 서버를 자동 실행합니다.
  • 별도 터미널에서 npx agentation-mcp server 를 끄고 두고, Cursor만 사용하면 같은 프로세스로 동작해서 어노테이션이 잘 보입니다.

3.2 터미널에서 직접 띄우는 경우

  • 프로젝트 루트에서 실행해야 프로젝트에 설치된 패키지가 사용됩니다.
  • agentation-mcp 는 전역 명령이 아니므로 반드시 npx 또는 pnpm exec 로 실행합니다.
# 프로젝트 루트에서
npx agentation-mcp server
# 또는
pnpm exec agentation-mcp server
  • 잘못된 예: agentation-mcp server → command not found (전역 PATH에 없음).

3.3 연결 확인

npx agentation-mcp doctor
  • Node 버전, (Claude Code인 경우) MCP 설정, Server (port 4747) 상태를 확인합니다.
  • Cursor만 쓰는 경우 "Claude Code config" 메시지는 무시해도 됩니다.

4. 사용 방법 (Cursor 기준)

4.1 MCP 서버 이름

  • Cursor에서 등록된 이름이 user-agentation 으로 보일 수 있습니다 (글로벌 설정일 때).
  • 채팅에서 "pending 가져와줘"라고 하면, 에이전트가 user-agentation 서버의 agentation_get_all_pending 를 호출합니다.

4.2 프롬프트로 할 수 있는 것

하고 싶은 것Cursor 채팅에 입력
미처리 어노테이션 목록 보기"Agentation pending 어노테이션 가져와줘"
처리 완료 표시"이 어노테이션 resolve 해줘" / "방금 수정한 거 resolve 해줘"
확인했다고 표시"이 어노테이션 acknowledge 해줘"
답글 달기"이 어노테이션에 reply로 [내용] 이라고 답해줘"

4.3 권장 사용 순서

  1. Cursor에서 한 번 "Agentation pending 어노테이션 가져와줘" 호출 → Cursor가 서버를 띄움.
  2. 브라우저에서 http://localhost:3000 (또는 dev-client 주소) 로 앱 접속.
  3. Agentation 툴바로 요소 선택 후 코멘트 추가.
  4. 다시 Cursor에서 "Agentation pending 어노테이션 가져와줘" → 방금 남긴 어노테이션이 목록에 포함됨.

5. 트러블슈팅

5.1 "Error - Show Output" (MCP 목록에서 agentation 빨간 점)

  • Show Output 클릭해서 에러 메시지 확인.
  • 흔한 원인: command not found(npx 경로), EADDRINUSE(4747 사용 중), Cannot find module(패키지 미설치).
  • 해결: pnpm install 또는 pnpm add -w agentation-mcp, 필요 시 터미널에서 띄운 서버 종료 후 Cursor 재시작.

5.2 fetch failed / pending이 계속 0건

  • MCP 연결 끊김: Cursor 완전 종료 후 재실행.
  • 서버가 두 개인 경우: 터미널의 npx agentation-mcp server 는 끄고, Cursor만 켠 뒤 위 4.3 순서로 사용.

5.3 글로벌 vs 프로젝트 MCP 설정 충돌

  • agentation을 글로벌(~/.cursor/mcp.json)에만 두고, 프로젝트 .cursor/mcp.json 에는 agentation을 넣지 않음 (또는 반대로 한쪽만 사용).
  • 두 곳에 다 있으면 병합/우선순위 때문에 에러나 빈 결과가 날 수 있음.

5.4 doctor에서 "Server (port 4747): Not running"

  • Cursor가 MCP로 agentation을 아직 한 번도 호출하지 않았으면 서버가 안 떠 있어서 Not running일 수 있음.
  • 채팅에서 "Agentation pending 어노테이션 가져와줘" 한 번 호출한 뒤 다시 doctor 해보면 통과할 수 있음.

6. 참고 파일·명령어 요약

항목경로 또는 명령
MCP 서버 패키지루트 package.json → agentation-mcp
툴바 패키지package.json → devDependencies agentation
툴바 렌더 위치src/pages/_app.tsx
Cursor 글로벌 MCP~/.cursor/mcp.json
프로젝트 MCP프로젝트/.cursor/mcp.json (agentation은 비워 둠)
서버 실행npx agentation-mcp server (프로젝트 루트)
연결 확인npx agentation-mcp doctor

7. 관련 문서

  • 상세 가이드: docs/AGENTATION_MCP_GUIDE.md (용어, MCP 도구 9개, Hands-Free/Critique/Self-Driving 모드 등)
  • 공식: Agentation MCP

이 문서는 Cursor와 Claude Code에서 Agentation을 연동하면서 정리한 내용을 바탕으로 작성되었습니다.

profile
Shin Jinseop
이전 포스트

딥러닝 모델 성능 지표 총정리

다음 포스트

디자인시스템 도입 가이드

0개의 댓글