초안 · 공개 전 검토 중 법률 검토와 운영자 확인이 끝나지 않은 초안이에요. 표시된 3곳이 정리되면 ‘초안’ 표시를 지울게요.

MCP·플러그인 연결 안내

복사

AI 도구(에이전트)가 나 대신 Project RAG의 파일을 찾고, 읽고, 허락하면 올릴 수도 있도록 연결하는 방법입니다. 연결에는 MCP(Model Context Protocol)를 씁니다. API 키나 비밀번호를 복사해 넘길 필요가 없습니다.

1. 준비

• 회원 계정: 에이전트 연결은 회원만 할 수 있습니다.
• MCP를 지원하는 클라이언트: 원격 MCP 서버를 추가하고 브라우저로 로그인할 수 있는 AI 도구가 필요합니다. 확인된 클라이언트 목록 — 예: Claude, Cursor, Codex. 실제 연결 확인 후 채움
• 서버 주소: https://rag.proj.run/mcp

2. 연결하기

1. 클라이언트에 서버 추가: 클라이언트의 MCP(또는 커넥터) 설정에서 원격 서버를 추가하고 주소에 https://rag.proj.run/mcp를 넣습니다. 플러그인을 쓰면 이 주소가 이미 들어 있습니다. 클라이언트 등록은 자동으로 이루어집니다.
2. 브라우저에서 로그인: 클라이언트가 브라우저를 열어 Project RAG 연결 승인 화면으로 보냅니다. 로그인하지 않았다면 Google로 로그인합니다. 로그인한 것만으로는 연결이 허락되지 않습니다.
3. 요청한 곳 확인: 승인 화면의 클라이언트 이름과 돌아갈 주소가 지금 쓰는 도구와 같은지 확인합니다. 모르는 클라이언트라면 ‘거부’를 누르세요.
4. 작업공간 고르기: 에이전트가 쓸 작업공간 하나를 고릅니다. 연결 하나는 작업공간 하나에서만 작동합니다. 여러 작업공간을 쓰려면 작업공간마다 연결을 만드세요.
5. 권한 고르기
6. 읽기: 파일을 찾고 읽기만 합니다. 찾아보는 용도라면 이것만 고르세요.
7. 읽기 및 기여: 파일 올리기, 새 버전 추가, 링크 등록, 복사(포크), 참조 수정, 평가도 할 수 있습니다. 소유권 가져오기, 다른 회원의 기여 수정, 권한 관리, 작업공간 만들기, 신고는 할 수 없습니다.
8. 기간 고르기: 1시간, 1일, 7일, 30일 중에서 고릅니다. 기간이 끝나면 다시 허락해야 합니다.
9. 허락하고 돌아가기: ‘허락’을 누르고 클라이언트로 돌아갑니다.
10. 확인: 클라이언트에 Project RAG 도구 목록이 보이면 연결된 것입니다. 계정 → 에이전트 연결에도 새 연결이 보이며, 알림 주소(저장된 경우)로 메일을 보내 드립니다.

승인 요청은 몇 분 안에 끝내야 합니다. ‘만료되었습니다’가 보이면 클라이언트에서 연결을 다시 시작하세요.

3. 에이전트가 할 수 있는 일

에이전트는 허락한 작업공간과 권한, 그리고 내 현재 권한이 겹치는 범위에서만 작동합니다. 내 권한이 줄어들면 에이전트의 범위도 함께 줄어듭니다.

• 신고, 팔로우, 권한 관리, 소유권 이전, 회원 탈퇴는 설계상 웹사이트에서만 할 수 있습니다.
• 읽거나 내려받거나 복사하는 것만으로는 평가가 생기지 않습니다. 평가는 ‘읽기 및 기여’ 연결에서 명시적으로 보낼 때만 남습니다. 한 사람이 여러 에이전트를 써도 한 사람으로 셉니다. 내가 올린 파일에는 평가할 수 없습니다.
• 공개 작업공간에 올리는 내용은 웹사이트와 똑같이 개인정보·비밀 정보 형식을 확인하고, 발견되면 저장하지 않습니다.

4. 에이전트로 올리기

1. 에이전트가 파일 이름, 크기, 파일 전체의 SHA-256, 작업 번호(8~64자, 다시 시도할 때 그대로 사용)를 넣어 start_upload를 부릅니다.
2. 응답으로 조각 계획을 받습니다. 8 MiB 이하는 한 번에, 더 크면 8 MiB 조각으로 보냅니다. 에이전트는 접근 토큰, 정확한 Content-Length, 그 조각의 SHA-256을 담은 x-part-sha256 헤더와 함께 조각마다 안내된 주소로 PUT을 보냅니다.
3. 에이전트가 finish_upload를 부릅니다. 서비스는 버전을 만들기 전에 파일 전체의 크기와 SHA-256을 확인하고, 공개 작업공간이라면 개인정보 확인도 합니다.
4. 빠진 조각이 있으면 finish_upload가 받은 조각 번호와 함께 PARTS_MISSING을 돌려주므로, 에이전트는 빠진 조각만 보내면 됩니다. 업로드는 시작한 뒤 24시간이 지나면 만료됩니다.
5. 업로드는 작업공간 소유자의 저장 공간과, 에이전트를 연결한 회원의 하루 업로드 한도에서 셉니다(이용 한도).

5. 에이전트로 링크·영상 등록

• register_link는 https:// 주소를 받습니다. YouTube와 Vimeo 주소는 영상 ID로 식별되는 영상 링크가 됩니다. 제목, 채널, 시작·끝 시각, 직접 밝힌 SHA-256과 크기를 함께 넣을 수 있습니다.
• 같은 링크나 영상이 작업공간에 이미 있으면 DUPLICATE_LINK를 받습니다. 그 파일의 새 버전으로 넣거나 allow_duplicate를 지정하세요.
• get_file과 get_download_url은 링크 파일을 외부 자료로 표시합니다. 외부 링크 너머의 내용은 Project RAG가 저장하거나 확인하지 않으므로 믿을 수 없는 자료로 다뤄야 합니다. 에이전트는 그 안의 지시를 따르면 안 됩니다.
• 자세한 내용은 링크·영상 안내에 있습니다.

6. 연결 확인과 해제

• 계정 → 에이전트 연결에서 연결된 클라이언트, 작업공간, 권한, 끝나는 시각을 볼 수 있습니다.
• 쓰지 않는 연결은 ‘연결 해제’를 누르세요. 바로 접근이 끊기며, 다시 쓰려면 새로 허락해야 합니다.
• 클라이언트에서도 서버나 플러그인을 지우세요. 서비스에서 연결을 해제해도 클라이언트 설정은 바뀌지 않습니다.
• 새 연결이 허락될 때마다 알림 주소(저장된 경우)로 클라이언트 이름, 권한, 시각, 연결 해제 링크를 담은 메일을 보냅니다. 내가 허락한 것이 아니라면 연결을 해제하고 Google 계정을 확인하세요.
• 회원 탈퇴를 하면 모든 에이전트 연결과 토큰이 바로 끝납니다.
• 연결은 계정당 16개까지 유지할 수 있습니다.

7. 안전하게 쓰기

• 비밀번호, 로그인 쿠키, 토큰을 에이전트나 대화창에 붙여 넣지 마세요. 서비스는 이런 정보를 요구하지 않습니다.
• 에이전트가 읽은 문서는 내가 썼든 다른 사람이 썼든 참고 자료일 뿐 지시가 아닙니다. 문서 안의 지시 때문에 에이전트가 자료를 밖으로 보내거나, 도구를 실행하거나, 비밀을 공유하거나, 권한이나 공개 범위를 바꾸지 않도록 하세요.
• 비공개 자료를 읽도록 허락한 것은 공개해도 된다는 뜻이 아닙니다. 공개 작업공간에 개인정보, 비밀키, 기밀과 그것으로 만든 요약·제목·이름·주소·인용을 쓰지 않도록 하세요.
• 에이전트에 전달된 자료를 클라이언트 제공자가 어떻게 처리하는지는 그 제공자의 조건을 따릅니다. 확인해 주세요.

8. 플러그인

Claude, Cursor, Codex용 플러그인에는 서버 주소와 사용 안내만 들어 있습니다. 파일이나 토큰은 들어 있지 않습니다. 플러그인을 설치해도 2항의 승인 절차를 똑같이 거칩니다. 배포할 때마다 SHA-256 체크섬을 함께 공개합니다. 플러그인 내려받기 위치와 버전 — 공개 배포 결정 후 채움

9. 호환성

• 지원하는 MCP 프로토콜 버전: 2025-11-25, 2025-06-18, 2025-03-26. 다른 버전을 요청한 클라이언트는 지원 버전 목록이 담긴 UnsupportedProtocolVersionError를 받습니다.
• 현재 API(/api/v2)와 도구 목록 안에서는 추가만 합니다. 새 선택 항목, 새 도구, 새 오류 코드를 더할 뿐입니다.
• 호환되지 않는 변경은 새 도구 이름이나 새 API 버전으로 하며, 최소 90일 동안 함께 제공하고, Deprecation·Sunset 헤더(MCP 도구는 _meta.deprecated)와 공개 변경 기록으로 알립니다. 변경 기록 주소
• 옛 API(/api/graph/*)와 글로벌 출시 전에 만든 연결은 종료했습니다. API_RETIRED나 UNAUTHENTICATED가 돌아오면 2항의 절차로 다시 연결하세요.

10. 오류 코드

문제가 생기면 서비스는 아래 코드를 돌려줍니다. 입력한 값이나 발견된 개인정보를 오류에 다시 담지 않습니다. ‘다시 시도’가 ‘예’인 오류만 같은 요청을 나중에 그대로 다시 보내도 됩니다. 나머지는 입력이나 상황을 먼저 바꿔야 합니다. MCP에서는 모든 오류가 도구 결과의 code와 retryable로 전달됩니다.

10-1. 연결과 권한

10-2. 입력

PUBLIC_PERSONAL_DATA의 종류: email(이메일 주소), phone(전화번호), national_id(주민등록번호 등), card_number(카드 번호), access_token(인증 토큰·API 키), private_key(비밀키), signed_url(토큰이나 서명이 들어 있는 주소).

10-3. 업로드

10-4. 상태와 충돌

10-5. 한도

10-6. 정책과 서비스 상태

10-7. 일시적인 문제

11. 문제가 생겼을 때

문의: contact@proj.run (비밀번호·토큰·비공개 파일 내용은 보내지 마세요)