여기까지 따라 하면 claude.ai의 평소 대화에서 osFoundry 프로젝트의 노트, 지식 베이스, 레코드를 열어 읽고, 그걸 근거로 답하고, 그 프로젝트의 토론 채널에 글까지 올릴 수 있다. 승인을 거치면 편집도 된다. Claude 로그인은 지금 쓰는 그대로다. 그 채팅이 무엇을 건드려도 되는지는 tool 호출이 있을 때마다 osFoundry가 판단하고, 호출 하나하나가 osFoundry의 연결별 Recent activity에 남는다. ChatGPT도 같은 서버 주소로 똑같이 붙일 수 있다.
누가 무엇을 맡나
| Claude 쪽 | osFoundry 쪽 | |
|---|---|---|
| 로그인 | 평소 쓰는 Claude 계정 그대로 | osFoundry 계정으로 연결을 한 번 승인한다(워크스페이스 하나) |
| 모델 실행 | 원래 쓰던 Claude 채팅 | 아무것도 안 돌린다. 이 경로에는 모델도 프로바이더 키도 없다 |
| tool 실행 위치 | Claude가 tool을 호출한다 | api.osfoundry.io가 권한부터 확인하고 실행한다 |
| 닿는 범위 | 서버가 돌려준 것만 | 연결을 추가한 프로젝트, 그리고 초대한 채널 |
| 승인 | Claude 자체의 tool 권한 확인 창 | GitNest와 Room 변경은 "Needs your approval"에서 대기한다 |
| 데이터 위치 | 답변은 Claude 채팅에 남는다 | 노트, 레코드, 문서는 osFoundry에 남는다. 로컬 전용 항목은 기기 밖으로 안 나간다 |
설정
1. osFoundry에서 연결 만들기
osFoundry 헤더의 열쇠 아이콘을 누르고 Connected 탭을 연다. 패널 제목은 "Connected agents"고, 지금 어느 워크스페이스에 있는지 같이 보인다. "Connect in three steps" 아래에서 이렇게 넣는다.
- Assistant: Claude 선택
- Display name: 나중에 알아볼 수 있는 이름이면 된다. 예:
Claude research - Add assistant(어시스턴트 추가) 클릭
새로 만든 연결에는 "Setup pending. This assistant cannot read or change anything yet."이라고 뜬다. 아직은 아무것도 못 읽는다는 뜻이다. Server address 옆의 Copy 버튼으로 주소를 복사한다.
https://api.osfoundry.io/api/v1/external-mcp 
예시: Add assistant 직후의 Connected 탭. 서버 주소와 설정 대기 중인 연결
2. Claude에 커스텀 커넥터로 추가하기
Claude에서 Customize → Connectors를 열고 이 URL로 커스텀 커넥터를 추가한다. Team이나 Enterprise 플랜이면 조직 owner가 먼저 Organization settings → Connectors에서 추가하고, 그다음에 멤버가 각자 연결한다. 원격 MCP 커넥터 절차는 Anthropic의 Claude 커스텀 커넥터 가이드에 정리돼 있다.
Connect를 누르면 Claude가 osFoundry 로그인 화면을 알아서 찾아간다. client ID나 키를 붙여 넣을 일은 없다.
3. 워크스페이스 하나만 승인하기
브라우저가 https://osfoundry.io/external-assistant-authorize로 넘어가고, "Connect an agent"라는 화면이 뜬다. 접속하려는 어시스턴트 클라이언트와 돌아갈 호스트가 표시되고, 그 아래에서 다음을 고른다.
- Workspace to connect: 워크스페이스 하나. 다른 워크스페이스를 쓰려면 연결을 따로 만들어야 한다.
- Requested capabilities: 요청 권한이 쉬운 말로 나온다. "Read supported resources in projects you add", "Change supported resources where you have edit access", "Run sessions where you grant a runner role".
- Connection: "Use pending: Claude research"를 고르면 1단계에서 만든 연결에 붙는다. "Create a new connection"으로 두면 새 연결이 생긴다.
- "I approve connecting this assistant to <워크스페이스>"에 체크하고 Connect.
그러면 Claude로 돌아온다. 연결은 살아 있지만 아직 아무것도 안 보인다. 새 연결은 프로젝트 0개에서 시작하기 때문이다.
4. 프로젝트에 추가하기
다시 열쇠 아이콘 → Connected로 가서 연결을 고르면 이제 "Connected."로 바뀌어 있다. Projects에서 프로젝트를 고르고 Add to project를 누른다.
예시: 프로젝트에 추가된 연결과 그 아래의 연결된 채팅
이걸로 그 프로젝트 안의 동기화된 지원 콘텐츠에 접근 권한이 생긴다. 노트, 지식 베이스, Record 채널, 클라우드 Room, 프로젝트에 할당된 GitNest 저장소, 그리고 프로젝트의 토론 채널이다. 나중에 프로젝트에 추가하는 콘텐츠도 포함된다. 일반 Message 채널은 별개다. 채팅이 읽고 답해야 하는 채널마다 Message channels → Choose a Message channel → Invite로 초대해 줘야 한다.
Tools 섹션에는 "All supported tools are on by default."라고 적혀 있다. 이 연결에 주고 싶지 않은 tool이 있으면 체크를 풀고 Save tools를 누른다.
예시: Claude 연결의 Tools 체크리스트. 기본값은 전부 켜짐
5. 채팅에서 켜기
Claude 대화에서 + 메뉴 → Connectors를 열고 osFoundry 커넥터를 켠다. 그다음엔 평소처럼 말로 부탁하면 된다.
실제로 돌려 보면
아래 프롬프트와 답변은 데모 프로젝트의 예시 콘텐츠다. tool 이름과 인자 이름은 실서버가 tools/list로 알려 주는 그대로다. claude.ai에서는 호출이 커넥터 이름 아래에 쭉 나온다. 같은 URL을 Claude Code에 osfoundry라는 이름으로 추가하면 같은 tool이 mcp__osfoundry__list_project_resources 같은 이름으로 보인다.
예시 나: osFoundry에서 Q3 런칭 체크리스트에 아직 안 끝난 게 뭐야? 서포트 KB랑 안 맞는 내용이 있는지도 확인하고, "pricing page" 레코드는 Ready로 바꿔 줘. Claude → list_granted_resources {} ← 연결된 프로젝트 1개: "Launch Q3" (워크스페이스) Claude → list_project_resources {"project_id": "…", "resource_type": "note", "search": "checklist"} ← 노트 "Q3 launch checklist" Claude → list_note_tabs {"note_id": "…"} ← 탭: Note (텍스트), Sheet "Owners" Claude → read_note_tab {"note_id": "…", "tab_id": "…"} ← 항목 9개, 미체크 3개 Claude → search_knowledge_base {"knowledge_base_id": "…", "query": "refund window"} ← 문서 "Refund policy" (2일 전 업데이트) Claude → read_record_item {"record_channel_id": "…", "item_id": "…"} ← "pricing page", status Draft, version … Claude → edit_record_item {"record_channel_id": "…", "item_id": "…", "values": {"status": "Ready"}, "expected_version": "…", "idempotency_key": "…"} [Claude가 이 tool 호출을 허용할지 묻는다 → Allow] ← 저장됨, 새 version … Claude: 남은 건 세 개야. 보도 엠바고 날짜, FAQ 번역, 그리고 pricing page의 환불 문구. 체크리스트에는 14일인데 KB 문서 "Refund policy"에는 30일로 돼 있어. pricing page 레코드는 Ready로 바꿨어. 이 기록에는 일부러 넣은 디테일이 두 개 있다. edit_record_item은 read_record_item이 돌려준 version을 요구한다. 그래서 그 사이에 누가 레코드를 바꿨다면 덮어쓰지 않고 거절된다. 그리고 같은 idempotency_key로 다시 보내면 첫 번째 결과가 돌아온다. 재시도해도 두 번 써지지 않는다.
어디까지 닿나
osFoundry는 Claude 채팅을 열 수 없다. MCP 연결은 Claude가 필요하다고 판단할 때 osFoundry tool을 부를 수 있게 해 줄 뿐이다. 반대 방향, 즉 osFoundry가 개인 대화를 나열하거나 읽거나 시작하는 API는 없다. 채팅을 프로젝트에 연결하는 tool(link_current_chat)도 채팅이 스스로 밝힌 라벨을 받는데, osFoundry는 이걸 확인된 신원이 아니라 라우팅 힌트로만 다룬다. 같은 이유로 Claude는 osFoundry에서 백그라운드 알림을 받지 않는다. 대화를 열고 부탁할 때만 움직인다.
로컬 전용 데이터는 로컬에 남는다. 서버도 initialize 응답에서 직접 "Local-only data is unavailable to cloud clients."라고 밝힌다. 로컬 Room, 로컬 Graph 세션, 한 번도 동기화되지 않은 콘텐츠는 연결에서 안 보인다. 데스크톱 Graph 세션 공유는 같은 탭에 있는 별도 스위치고, 데스크톱 앱이 열려 있고 로그인돼 있어야 한다.
권한은 로그인할 때가 아니라 호출마다 확인한다. 호출 하나하나를 연결 상태, 워크스페이스, 지금 시점의 프로젝트 멤버십, 그 아이템이 지금 어느 프로젝트에 있는지, 그리고 그 아이템에 대한 내 역할과 대조한다. 노트를 다른 프로젝트로 옮기거나, 프로젝트를 빼거나, Revoke connection을 누르면 바로 다음 호출부터 거절된다. 편집은 연결을 승인한 사람, 즉 내가 아직 편집 권한을 갖고 있어야 된다.
일부 쓰기는 제안이 된다. GitNest 작업, change set, 파일 가져오기, 풀 리퀘스트, Room 앱 설치는 propose_… tool을 거친다. 이건 Connected 탭의 "Needs your approval"에 쌓이고, 대상 저장소나 Room, 파일을 확인한 다음 Approve나 Decline을 고르면 된다. Git 프로바이더 토큰이나 시크릿 값이 Claude에 넘어가는 일은 없다.
Message 채널은 초대가 필요하다. 프로젝트에 들어 있다고 열리는 건 그 프로젝트의 토론 채널뿐이다. 다른 채널은 전부 따로 Invite해야 하고, 비공개 채널은 owner가 초대해야 한다.
다음 단계
같은 프로젝트에 지식 베이스를 추가하고, 평소라면 거기서 찾아 답했을 질문을 Claude에게 던져 보자. 예를 들면 "환불에 대해 KB에 뭐라고 돼 있어? 문서 이름도 같이 알려 줘." search_knowledge_base는 문서 ID와 마지막 업데이트 시점을 돌려주니까 출처를 바로 확인할 수 있다. osFoundry 지식 베이스가 어떻게 구성되는지는 지식 베이스 소개 페이지에 있다.
