MCP 연동 가이드

AI 개발 도구로 컨텍스트를 흘려보내세요

Claude Code · Cursor · Codex에서 PJT AI의 프로젝트 컨텍스트를 직접 참조합니다.

01MCP란?#

MCP(Model Context Protocol)는 AI 모델이 외부 시스템 데이터를 안전하게 참조하게 하는 표준입니다. PJT AI는 @apexstack/agent 패키지의 stdio MCP 서버(pjt-agent-mcp)를 제공합니다. 내 PC의 Claude Code 가 워크스페이스 데이터를 직접 조회할 수 있고, 읽기 전용입니다.

Claude Code 에서 다음 도구로 데이터를 조회합니다:

도구	설명
`get_project`	프로젝트 기본 정보 (id 또는 publicId `p_xxx`)
`list_project_tasks`	태스크 목록 (상태 필터 가능)
`get_task`	태스크 상세
`get_document`	문서 상세 (content 포함)
`list_workspace_documents`	워크스페이스 문서 목록
`get_workspace_snapshot`	워크스페이스 번들 (최근 문서 등)

ⓘ

작업 실행과는 별개

MCP 는 데이터 조회 전용입니다. 작업 자동 실행(pjt-agent start)과 독립적으로 동작하며, start 없이도 됩니다. 인증은 기존 Claude Code 에이전트 토큰(pjta_…)을 그대로 재사용합니다.

02Claude Code 연결#

전제: 로컬에 Node.js 18+ 와 Anthropic claude CLI 가 설치돼 있어야 합니다.

1. 토큰 발급

워크스페이스 설정 → Claude Code 에이전트 → “에이전트 추가” 에서 토큰(pjta_…)을 발급합니다. 발급 직후 화면에 등록 명령이 토큰이 채워진 채 표시됩니다(토큰은 그때 1회만 노출). 작업 실행 에이전트와 같은 토큰을 씁니다.

2. 설치

bash

npm install -g @apexstack/agent

3. 등록 — 한 줄 (권장)

로그인 없이 토큰·주소를 --env 로 주입하면 한 줄로 끝납니다.

bash

claude mcp add pjt-workspace \
  --env PJT_AGENT_TOKEN=pjta_xxx \
  --env PJT_API_URL=https://api.pjt.ai \
  -- pjt-agent-mcp

또는 login(토큰 파일 저장) 후 짧게 등록할 수도 있습니다:

bash

pjt-agent login --token pjta_xxx
claude mcp add pjt-workspace -- pjt-agent-mcp

4. 동작 확인

bash

$ claude
> 이 워크스페이스의 최근 문서를 보여줘

[pjt-workspace] get_workspace_snapshot → 문서 8건
[Claude] 최근 문서 8건입니다:
1. 봄 캠페인 기획서 (06/07)
2. ...

✓

연결 성공

claude mcp list 에 pjt-workspace 가 보이고, 대화에서 위 도구 호출 로그가 뜨면 정상입니다.

03Cursor (준비 중)#

ⓘ

6월 출시 예정

Cursor IDE의 MCP 지원 정식 출시에 맞춰 가이드를 공개합니다. 베타 액세스를 원하시면 [email protected] 로 문의하세요.

04Codex (준비 중)#

ⓘ

7월 출시 예정

OpenAI Codex 연동은 7월 첫째 주 출시 예정입니다.

05컨텍스트 범위#

MCP는 기본적으로 사용자가 멤버로 속한 프로젝트의 컨텍스트만 노출합니다. 세분화 제어는 다음과 같이 가능합니다:

범위	기본	제어 방법
프로젝트 단위	멤버십 기반	워크스페이스 설정 > 권한
민감 필드	예산·견적 포함	설정에서 제외 가능
회의록	전문 노출	요약본만 노출 옵션

06보안 · 권한#

읽기 전용 — MCP 로는 데이터를 변경/삭제할 수 없습니다 (조회 only)
Claude Code 에이전트 토큰(pjta_) 재사용 — 별도 키 없음, 에이전트 단위로 폐기·재발급
토큰은 발급 시 1회만 노출 — 분실 시 재발급. 로컬은 ~/.pjt/agent.json (권한 0600)
전송·저장 시 모두 암호화 (TLS 1.3 + AES-256), 모든 액세스는 감사 로그에 기록
AI 학습에 사용되지 않음 — 데이터 소유권은 워크스페이스에
Enterprise는 SSO/SAML과 데이터 거주지 선택 (US · EU · KR)

MCP 연동 가이드

AI 개발 도구로 컨텍스트를 흘려보내세요

Claude Code · Cursor · Codex에서 PJT AI의 프로젝트 컨텍스트를 직접 참조합니다.

01MCP란?#

Claude Code 에서 다음 도구로 데이터를 조회합니다:

도구	설명
`get_project`	프로젝트 기본 정보 (id 또는 publicId `p_xxx`)
`list_project_tasks`	태스크 목록 (상태 필터 가능)
`get_task`	태스크 상세
`get_document`	문서 상세 (content 포함)
`list_workspace_documents`	워크스페이스 문서 목록
`get_workspace_snapshot`	워크스페이스 번들 (최근 문서 등)

ⓘ

작업 실행과는 별개

02Claude Code 연결#

전제: 로컬에 Node.js 18+ 와 Anthropic claude CLI 가 설치돼 있어야 합니다.

1. 토큰 발급

2. 설치

bash

npm install -g @apexstack/agent

3. 등록 — 한 줄 (권장)

로그인 없이 토큰·주소를 --env 로 주입하면 한 줄로 끝납니다.

bash

claude mcp add pjt-workspace \
  --env PJT_AGENT_TOKEN=pjta_xxx \
  --env PJT_API_URL=https://api.pjt.ai \
  -- pjt-agent-mcp

또는 login(토큰 파일 저장) 후 짧게 등록할 수도 있습니다:

bash

pjt-agent login --token pjta_xxx
claude mcp add pjt-workspace -- pjt-agent-mcp

4. 동작 확인

bash

$ claude
> 이 워크스페이스의 최근 문서를 보여줘

[pjt-workspace] get_workspace_snapshot → 문서 8건
[Claude] 최근 문서 8건입니다:
1. 봄 캠페인 기획서 (06/07)
2. ...

✓

연결 성공

claude mcp list 에 pjt-workspace 가 보이고, 대화에서 위 도구 호출 로그가 뜨면 정상입니다.

03Cursor (준비 중)#

ⓘ

6월 출시 예정

Cursor IDE의 MCP 지원 정식 출시에 맞춰 가이드를 공개합니다. 베타 액세스를 원하시면 [email protected] 로 문의하세요.

04Codex (준비 중)#

ⓘ

7월 출시 예정

OpenAI Codex 연동은 7월 첫째 주 출시 예정입니다.

05컨텍스트 범위#

MCP는 기본적으로 사용자가 멤버로 속한 프로젝트의 컨텍스트만 노출합니다. 세분화 제어는 다음과 같이 가능합니다:

범위	기본	제어 방법
프로젝트 단위	멤버십 기반	워크스페이스 설정 > 권한
민감 필드	예산·견적 포함	설정에서 제외 가능
회의록	전문 노출	요약본만 노출 옵션

06보안 · 권한#

읽기 전용 — MCP 로는 데이터를 변경/삭제할 수 없습니다 (조회 only)
Claude Code 에이전트 토큰(pjta_) 재사용 — 별도 키 없음, 에이전트 단위로 폐기·재발급
토큰은 발급 시 1회만 노출 — 분실 시 재발급. 로컬은 ~/.pjt/agent.json (권한 0600)
전송·저장 시 모두 암호화 (TLS 1.3 + AES-256), 모든 액세스는 감사 로그에 기록
AI 학습에 사용되지 않음 — 데이터 소유권은 워크스페이스에
Enterprise는 SSO/SAML과 데이터 거주지 선택 (US · EU · KR)