Codex CLI에 osFoundry MCP 연결…프로젝트 문서 조회와 쓰기 승인 설정

Codex CLI가 저장소에서 코드를 수정하기 전에 osFoundry의 스펙 노트, 지원용 지식 베이스, 버그 레코드를 조회하도록 연결하는 방법이 개발자 커뮤니티 데브 커뮤니티(Dev Community)에 소개됐다. MCP 서버를 통해 자료를 읽고, 쓰기 작업에는 사전 확인을 요구하도록 설정하는 방식이다.

이 연결에서는 사용자 머신의 Codex가 기존 로그인과 요금제로 모델을 실행하고 HTTPS로 툴을 호출한다. osFoundry의 api.osfoundry.io는 호출 권한을 확인한 뒤 작업을 처리하며, 이 경로에 별도 모델이나 프로바이더 키는 없다. osFoundry OAuth 토큰은 Codex가 보유한다. 답변과 코드 변경 내역은 Codex 세션에, 노트·레코드·문서는 osFoundry에 남는다.

접근 범위는 연결을 추가한 프로젝트와 별도로 초대한 채널에 한정된다. 호출할 때마다 연결 상태, 워크스페이스, 현재 프로젝트 참여 여부, 항목이 속한 프로젝트, 사용자의 역할을 확인한다. 노트를 다른 프로젝트로 옮기거나 프로젝트를 연결에서 제외하거나 연결을 해제하면, 토큰이 만료되지 않았더라도 다음 호출은 거절된다. 로컬 Room, 로컬 Graph 세션, 아직 동기화하지 않은 자료는 이 연결로 볼 수 없다.

설정은 osFoundry 헤더의 열쇠 아이콘을 눌러 Connected 탭을 여는 데서 시작한다. Connected agents 화면에서 현재 워크스페이스를 확인하고 Assistant를 Other MCP client로, Display name을 Codex CLI처럼 알아보기 쉬운 이름으로 지정한다. Add assistant를 누르면 아직 읽기와 변경을 할 수 없는 설정 대기 상태로 연결이 생성된다. 서버 주소는 https://api.osfoundry.io/api/v1/external-mcp다.

Codex에서는 codex mcp add osfoundry –url https://api.osfoundry.io/api/v1/external-mcp 명령으로 서버를 추가한다. 이어 ~/.codex/config.toml에 생성된 [mcp_servers.osfoundry] 테이블에서 scopes를 ["osfoundry:read", "osfoundry:write"]로 지정하고 default_tools_approval_mode를 "writes"로 설정한다. 범위를 명시하지 않으면 Codex는 서버 챌린지나 보호된 리소스 메타데이터에서 권한 범위를 가져온다. osFoundry 메타데이터에는 osfoundry:run을 포함한 네 가지 범위가 있지만, 레코드 조회와 수정만 하는 용도에는 세션 실행 권한까지 필요하지 않다는 설명이다.

원문의 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으로 구성된다. 서버가 제공하는 59개 툴 중 10개만 모델에 노출하는 구성이다. osFoundry는 툴에 readOnlyHint를 표시하므로 "writes" 설정에서 읽기 툴 9개는 확인 없이 실행되고 edit_record_item은 먼저 승인을 요청한다. 툴 이름에는 접두사를 붙이지 않으며, 오타가 있어도 오류 메시지 없이 해당 툴이 목록에서 빠질 수 있다. 특정 저장소에만 적용하려면 그 저장소의 .codex/config.toml에 같은 테이블을 넣는다. Codex는 신뢰한 프로젝트의 설정만 읽는다.

로그인은 codex mcp login osfoundry로 진행한다. 브라우저에서 https://osfoundry.io/external-assistant-authorize가 열리면 연결할 워크스페이스 하나를 고른다. 다른 워크스페이스에는 별도 연결이 필요하다. 앞서 지정한 범위로는 추가한 프로젝트의 지원 리소스를 읽고, 편집 권한이 있는 리소스를 변경하는 기능을 요청한다. Connection에서 Use pending: Codex CLI를 선택해 대기 중인 연결과 로그인을 묶은 뒤 승인 항목에 체크하고 Connect를 누른다. Codex가 사용자 머신에서 콜백을 받으므로 Returns to에는 로컬 주소가 표시된다.

SSH로 접속한 원격 머신에서는 codex mcp login osfoundry –no-browser가 출력한 URL을 노트북에서 열고, 리다이렉트된 URL 전체를 터미널에 붙여 넣으면 된다. osFoundry 서버가 클라이언트 등록 엔드포인트와 퍼블릭 클라이언트를 지원하므로 Codex가 자동으로 등록하며, 클라이언트 ID를 직접 입력할 필요는 없다.

로그인 후 Connected 탭에서 연결 상태를 확인하고 Projects에서 프로젝트를 골라 Add to project를 누른다. 해당 프로젝트의 동기화된 노트, 지식 베이스, Record 채널, 클라우드 Room, 할당된 GitNest 저장소, 토론 채널과 이후 추가되는 항목에 접근할 수 있다. 다른 Message 채널은 각각 초대해야 한다. Tools 섹션은 지원 툴이 모두 켜진 상태로 시작하므로, 연결에서 허용하지 않을 툴은 체크를 해제하고 Save tools로 저장한다. Codex TUI에서 /mcp를 입력하면 활성 서버 목록에 osfoundry가 있는지 확인할 수 있다.

로컬 설정의 enabled_tools와 osFoundry의 Tools 체크리스트는 역할이 다르다. 전자는 모델에 보일 툴을 정하고, 후자는 로컬 설정을 바꾸더라도 유지되는 연결 소유자 측 통제 수단이다. 어느 쪽도 리소스 접근 권한 자체를 부여하지 않으며, 접근 권한은 프로젝트 참여로 결정된다. osFoundry는 호출마다 툴 이름, 권한 판정, 시각을 Recent activity에 기록한다. 다만 Codex 세션이나 저장소, 터미널을 열어 볼 수는 없고, 이 연결을 통해 소스 코드가 전달되는 경우는 Codex가 레코드 댓글 등 툴 인자에 코드를 넣었을 때다.

원문에 제시된 환불 테스트 수정 과정은 실제 실행 결과가 아닌 시뮬레이션이다. 작성 머신에는 Codex가 설치돼 있지 않았으며, 툴 이름만 라이브 서버의 tools/list 응답을 따랐다. 예시에서는 14일을 기준으로 실패하는 tests/test_refund.py를 수정하기 전에 스펙 노트와 지원 지식 베이스를 조회한다. 두 자료의 환불 기간이 30일임을 확인한 뒤 테스트와 상수 주석을 고치고 pytest 테스트 12개를 통과한 것으로 묘사된다. 이어 사용자가 Codex의 확인 창에서 승인하자 환불 기간이 16일 어긋난다는 레코드를 Fixed로 변경한다. 프로젝트, 프롬프트, 답변도 데모용으로, 실제 검증 성과를 뜻하지 않는다.

레코드 수정에는 read_record_item이나 list_record_items가 반환한 버전을 expected_version으로 함께 보낸다. 조회 이후 다른 사용자가 내용을 바꿨다면 덮어쓰지 않고 요청을 거절한다. 같은 idempotency_key로 재시도하면 첫 결과를 반환해 중복 쓰기를 막는다. 이때 사전 확인 창을 띄우는 주체는 osFoundry가 아니라 default_tools_approval_mode를 "writes"로 설정한 Codex다.

GitNest 작업, change set, 파일 가져오기, 풀 리퀘스트는 propose_… 툴을 통한 제안으로 처리된다. 대상과 파일 목록이 Connected 탭의 Needs your approval에 표시되고 사용자가 승인하거나 거절할 때까지 대기한다. Codex는 Git 프로바이더 토큰을 받지 않는다. 원문의 설정 예시는 Codex에 로컬 체크아웃이 있다는 이유로 이들 툴을 제외했다. 활용 예로는 지원 지식 베이스를 연결해 문서 문자열이나 오류 메시지가 문서 설명과 일치하는지 비교하는 작업을 들었다. search_knowledge_base가 문서 ID와 마지막 업데이트 시점을 함께 반환하므로 참조 자료를 확인할 수 있다.