Codex CLI가 osFoundry 노트와 지식 베이스를 MCP로 읽게 하는 방법

목표는 Codex CLI가 저장소에서 작업하다가 osFoundry 프로젝트에 있는 스펙 노트, 지원용 지식 베이스, 버그 레코드를 직접 찾아보는 상태다. 읽기는 osFoundry MCP 서버를 거치고, 뭔가를 쓰기 전에는 꼭 확인을 받는다. Codex가 한 호출은 전부 osFoundry 쪽 연결의 Recent activity(최근 활동)에 남는다. 할 일은 세 가지다. ~/.codex/config.toml에 테이블 하나 추가, 브라우저에서 로그인 한 번, 클릭 한 번으로 연결을 프로젝트에 넣기.

누가 뭘 맡나

설정

1. osFoundry에서 연결 만들기

osFoundry 헤더의 열쇠 아이콘을 눌러 Connected 탭을 연다. 제목은 "Connected agents"고 그 밑에 지금 워크스페이스 이름이 보인다. "Connect in three steps" 아래 폼에 이렇게 넣는다.

• Assistant: Other MCP client
• Display name: 알아보기 쉬운 이름, 예를 들어 Codex CLI
• Add assistant(어시스턴트 추가)를 누른다

연결은 "Setup pending. This assistant cannot read or change anything yet." 상태로 목록에 뜬다. Server address를 복사해 둔다.

https://api.osfoundry.io/api/v1/external-mcp

예시: Codex CLI 연결을 선택한 Connected 탭

2. Codex에 서버 추가하기

OpenAI Codex MCP 문서에 나온 한 줄이면 된다.

codex mcp add osfoundry --url https://api.osfoundry.io/api/v1/external-mcp

이러면 [mcp_servers.osfoundry] 테이블이 생긴다. ~/.codex/config.toml을 열어서 좀 더 조여 두자. 아래 키는 전부 그 문서에 있는 것들이다.

[mcp_servers.osfoundry]
url = "https://api.osfoundry.io/api/v1/external-mcp"
scopes = ["osfoundry:read", "osfoundry:write"]
default_tools_approval_mode = "writes"
enabled_tools = [
  "list_granted_resources",
  "list_project_resources",
  "list_note_tabs",
  "read_note_tab",
  "read_sheet_range",
  "search_knowledge_base",
  "read_knowledge_article",
  "list_record_items",
  "read_record_item",
  "edit_record_item",
]

줄마다 하는 일은 이렇다.

• scopes는 서버가 제시하는 스코프를 대신한다. 안 쓰면 Codex는 서버 챌린지나 protected resource metadata에서 스코프를 가져오는데, osFoundry 메타데이터에는 osfoundry:run을 포함해 네 개가 있다. 레코드를 읽고 고치기만 하는 코딩 어시스턴트한테 세션 실행 권한까지는 필요 없다.
• default_tools_approval_mode = "writes"는 read-only 표시가 없는 툴마다 확인 창을 띄운다. osFoundry는 툴에 readOnlyHint를 달아 두기 때문에 읽기 툴 9개는 확인 없이 돌고 edit_record_item만 먼저 물어본다.
• enabled_tools는 툴 목록을 짧게 유지한다. 서버가 내놓는 툴은 59개고, 이 목록은 10개다. 이름은 접두사 없는 MCP 원래 툴 이름으로 쓴다. 여기서 잘 삽질하는 게 오타다. 이름을 틀려도 에러가 안 나고, 그 툴이 그냥 없을 뿐이다.

특정 저장소에서만 쓰고 싶으면 같은 테이블을 그 저장소의 .codex/config.toml에 넣으면 된다. 다만 Codex는 trusted(신뢰함)로 표시한 프로젝트의 설정만 읽는다.

3. 로그인하기

codex mcp login osfoundry

브라우저에서 https://osfoundry.io/external-assistant-authorize가 열리고 "Connect an agent"라는 화면이 나온다. Assistant client와 "Returns to"가 보이는데, Codex가 콜백을 내 머신에서 받기 때문에 Returns to는 로컬 주소다. 그다음은 이렇다.

• Workspace to connect: 하나를 고른다. 다른 워크스페이스는 연결을 따로 만들어야 한다.
• Requested capabilities: 위의 scopes라면 "Read supported resources in projects you add"와 "Change supported resources where you have edit access" 두 줄이 보인다.
• Connection: "Use pending: Codex CLI"를 골라서 1단계에서 만든 연결에 로그인을 붙인다.
• "I approve connecting this assistant to <워크스페이스>"에 체크하고 Connect를 누른다.

SSH로 들어간 원격 머신이라면 codex mcp login osfoundry --no-browser가 URL을 대신 출력한다. 그 URL을 노트북에서 열고, 리다이렉트된 URL 전체를 터미널에 다시 붙여 넣으면 된다.

osFoundry 서버에는 클라이언트 등록 엔드포인트가 있고 퍼블릭 클라이언트를 받아 주기 때문에, Codex가 알아서 등록한다. 클라이언트 ID를 붙여 넣을 일은 없다.

4. 연결을 프로젝트에 넣기

열쇠 아이콘 → Connected로 돌아오면 연결이 "Connected."로 바뀌어 있다. Projects에서 프로젝트를 고르고 Add to project(프로젝트에 추가)를 누른다. 그러면 그 프로젝트의 동기화된 노트, 지식 베이스, Record 채널, 클라우드 Room, 할당된 GitNest 저장소, 토론 채널이 열린다. 나중에 추가되는 것도 포함이다. 그 밖의 Message 채널은 하나씩 Invite(초대)해야 한다.

Tools 섹션은 "All supported tools are on by default." 상태로 시작한다. 누가 나중에 config.toml을 고쳐도 이 연결이 절대 부르면 안 되는 툴이 있으면 체크를 풀고 Save tools(툴 저장)를 누른다.

예시: 읽기 툴만 체크한 Tools 체크리스트와 Save tools

5. Codex에서 확인하기

codex TUI에서 /mcp를 치면 활성화된 서버 목록이 나온다. 거기 osfoundry가 있으면 된다. 그다음은 그냥 평소 말로 부탁하면 된다.

실제로 돌려 보면

이 글을 쓴 머신에는 Codex가 설치돼 있지 않아서, 아래 세션은 시뮬레이션한 예시다. 툴 이름은 라이브 서버가 tools/list로 돌려주는 그대로다. Codex 소스는 모델에 보이는 이름에서 MCP 툴 앞에 mcp____를 붙이기 때문에 여기서도 그렇게 적었다. 프롬프트, 프로젝트, 답변은 데모용 내용이다.

예시 (시뮬레이션)

> tests/test_refund.py에서 실패하는 테스트는 환불 기간을 14일로 보고 있어.
  고치기 전에 osFoundry 스펙이랑 지원 KB부터 확인해 줘.

• mcp__osfoundry__list_granted_resources {}
  ← 프로젝트 1개: "Billing v2"
• mcp__osfoundry__list_project_resources {"project_id": "…", "resource_type": "note", "search": "환불"}
  ← 노트 "환불 규칙 (스펙)"
• mcp__osfoundry__list_note_tabs {"note_id": "…"}
  ← 탭: Note (텍스트), Sheet "예외 케이스"
• mcp__osfoundry__read_note_tab {"note_id": "…", "tab_id": "…"}
  ← "환불은 청구일로부터 30일 이내에 접수한다…"
• mcp__osfoundry__search_knowledge_base {"knowledge_base_id": "…", "query": "환불 기간"}
  ← 문서 "환불 정책", 2일 전 업데이트: 30일
• edited src/billing/refund.py, tests/test_refund.py
• mcp__osfoundry__edit_record_item {"record_channel_id": "…", "item_id": "…",
      "values": {"status": "Fixed"}, "expected_version": "…", "idempotency_key": "…"}
  [Codex: 이 툴 호출을 허용할까요? → 예]
  ← saved

틀린 건 코드가 아니라 테스트였습니다. 스펙 노트와 KB 문서 둘 다
30일이라고 되어 있습니다. 테스트와 상수 주석을 고치고 pytest를 돌렸고
(12개 통과), "환불 기간이 16일 어긋남" 레코드를 Fixed로 바꿨습니다.

edit_record_item에는 read_record_item이나 list_record_items가 돌려준 버전이 같이 실린다. 그사이 누가 레코드를 바꿨으면 덮어쓰지 않고 거절된다. 같은 idempotency_key로 다시 보내면 첫 결과가 그대로 돌아오니까, 재시도해도 두 번 쓰이지 않는다. 중간의 승인 확인은 osFoundry가 아니라 Codex가 띄운 거고, default_tools_approval_mode = "writes" 덕분이다.

선은 어디에 있나

Codex는 osFoundry를 읽지만, osFoundry는 Codex를 읽지 않는다. 이 연결은 Codex가 필요하다고 판단할 때 툴을 부를 수 있게 해 줄 뿐이다. osFoundry는 호출마다 툴 이름, 권한 판정, 시각을 Recent activity에 남기지만, Codex 세션이나 저장소, 터미널을 열어 볼 수는 없다. 소스 코드는 Codex가 툴 인자(예를 들어 레코드 댓글)에 넣지 않는 한 어디로도 안 나간다.

필터 두 개는 하는 일이 다르다. config.toml의 enabled_tools는 모델에 뭘 보여 줄지 정한다. 프롬프트를 짧게, 선택지를 뻔하게 만드는 용도다. osFoundry의 Tools 체크리스트는 소유자 쪽 스위치고, 로컬 파일에 뭐라고 쓰여 있든 계속 효력이 있다. 둘 다 어떤 것에 대한 접근 권한을 주지는 않는다. 그건 프로젝트 참여가 정한다.

권한은 호출 단위로 판정된다. 호출할 때마다 연결 상태, 워크스페이스, 현재 프로젝트 참여, 그 항목이 지금 속한 프로젝트, 그리고 그 프로젝트에서의 내 역할을 확인한다. 노트를 다른 프로젝트로 옮기거나, 프로젝트를 빼거나, Revoke connection(연결 해제)을 누르면 토큰이 아직 만료되지 않았어도 Codex의 다음 호출은 거절된다.

어떤 쓰기는 제안으로 처리된다. GitNest 작업, change set, 파일 가져오기, 풀 리퀘스트는 propose_… 툴을 거쳐서, 대상과 파일 목록이 붙은 채로 Connected 탭의 "Needs your approval"에서 Approve나 Decline을 누를 때까지 기다린다. Codex가 Git 프로바이더 토큰을 받는 일은 없다. 어차피 Codex 손에는 로컬 체크아웃이 있으니까, 위 설정 예시에서는 이 툴들을 아예 뺐다.

로컬 전용 데이터는 로컬에 머문다. 서버의 initialize 응답에도 "Local-only data is unavailable to cloud clients."라고 나온다. 로컬 Room, 로컬 Graph 세션, 아직 동기화되지 않은 것은 이 연결로는 안 보인다.

다음에 해 볼 것

평소 질문에 답할 때 쓰는 지식 베이스를 Codex에 물려 주고, docstring이나 에러 메시지를 거기에 대 보게 하자. 예를 들면 "이 에러 문구, KB에 적힌 설명이랑 코드가 출력하는 거랑 맞아?" 같은 식이다. search_knowledge_base는 문서 ID와 마지막 업데이트 시점도 돌려주니까 출처를 확인하기 쉽다. osFoundry가 지식 베이스를 어떻게 정리하는지는 지식 베이스 페이지에 있다.