Codex는 MCP를 조금 다르게 처리해요
Claude Desktop이나 Cursor에 MCP 서버를 추가해본 적이 있다면 JSON을 편집해 왔을 거예요. Codex CLI는 JSON을 쓰지 않아요. 설정은 ~/.codex/config.toml에 있고, MCP 서버는 서버당 하나씩 [mcp_servers.<name>] 테이블에 들어가요.
두 번째 특이점이 있어요. Codex는 두 종류의 MCP 서버를 지원해요. 자식 프로세스로 실행하는 로컬 stdio 서버(command와 args를 넘겨줌)와 네트워크로 연결하는 원격 스트리밍 HTTP 서버(url을 넘겨줌)입니다. BankBridge는 원격 방식으로, 그냥 가리키기만 하면 되는 호스팅 서버예요. 그리고 현재 원격 서버는 기능 플래그 뒤에 숨겨져 있어요. 이 플래그를 놓치면 Codex는 경고 한 마디 없이 도구를 하나도 로드하지 않아요.
OpenAI의 문서는 메커니즘은 다루지만 완전히 작동하는 예시가 부족해요. 아마 그래서 여기까지 오셨을 거예요. 전체 설정은 TOML 네 줄과 환경 변수 하나예요.
BankBridge API 키 발급하기
BankBridge는 에이전트에게 실시간 은행 데이터에 대한 읽기 전용 접근을 제공하는 호스팅 MCP 서버예요. bankbridge.money에서 이메일로 가입한 뒤(매직 링크 방식, 비밀번호 없음) 대시보드에서 은행을 연결하세요.
연결 과정은 은행이 제공하는 안전한 UI 안에서 진행돼요. 기관을 선택하고 거기서 로그인한 뒤 읽기 전용 접근을 승인해요. BankBridge는 암호화된 접근 토큰을 저장하고, 은행 비밀번호는 절대 저장하지 않으며, 금융 데이터는 저희 서버에 캐시되지 않아요. Codex가 던지는 모든 질문은 실시간 조회로 답변돼요.
은행을 연결한 뒤에는 API 키를 만드세요. 키는 bbk_로 시작하고 딱 한 번만 표시되니 지금 복사해 두세요. 가격은 연결된 은행 하나당 월 $5이고, 언제든 취소할 수 있어요.
config.toml 항목
~/.codex/config.toml을 여세요. 파일이 없다면 만들면 돼요. 다음을 추가하세요:
experimental_use_rmcp_client = true
[mcp_servers.bankbridge]
url = "https://bankbridge.money/api/mcp"
bearer_token_env_var = "BANKBRIDGE_API_KEY"
알아둘 게 세 가지 있어요. 첫째, experimental_use_rmcp_client = true는 최상단 설정이에요. 어떤 [section] 헤더보다도 위에 있어야 해요. TOML은 모든 키를 자기 위에 있는 테이블 아래에 배치하기 때문에, 이 플래그가 [mcp_servers.bankbridge] 안으로 들어가면 Codex는 이걸 이상한 서버 옵션으로 취급하고 원격 서버는 결코 로드되지 않아요.
둘째, url은 BankBridge의 호스팅 엔드포인트를 가리켜요. 설치할 것도, npx 래퍼도, 관리해야 할 로컬 프로세스도 없어요.
셋째, bearer_token_env_var는 키 자체를 담는 대신 환경 변수의 이름을 지정해요. Codex가 셸에서 실제 비밀 값을 읽어오기 때문에, 공개된 dotfile 저장소에 올라가곤 하는 이 파일에 비밀 값이 들어가지 않아요.
셸에서 키 export하기
한 줄이에요:
export BANKBRIDGE_API_KEY="bbk_your_key_here"
Codex를 실행할 터미널에서 실행하고, 새 셸에서도 반영되도록 ~/.zshrc나 ~/.bashrc에도 추가해 두세요. 환경 변수에 키를 두면 교체도 간단해져요. export만 바꾸고 TOML은 그대로 두면 돼요. 키를 교체해야 할 때를 위한 짧은 가이드도 준비돼 있어요.
11개 도구가 로드됐는지 확인하기
codex 명령으로 새 세션을 시작하세요. TUI 안에서 /mcp를 입력하세요. Codex는 설정된 각 서버와 노출된 도구를 나열해줘요. 최근 빌드에는 세션을 시작하지 않고도 셸에서 실행할 수 있는 codex mcp list 하위 명령도 포함돼 있어요.
찾아야 할 건 11개 도구가 있는 bankbridge예요: list_accounts, get_account, list_transactions, search_transactions, get_spending_summary, get_recurring_charges, get_monthly_cashflow, get_merchant_history, list_categories, list_holdings, list_investment_transactions.
그리고 실제 질문을 던져보세요:
이번 주에 얼마나 썼어?
Codex는 get_spending_summary나 list_transactions를 호출해 실제 계정의 숫자를 돌려줄 거예요. 동기화 단계도, 스냅샷도 없어요. 모든 답은 질문한 순간에 실시간으로 가져와요.
Codex가 도구를 하나도 로드하지 않는다면
실패는 조용히 일어나서, 오히려 크래시보다 더 짜증나요. 다음을 순서대로 확인해보세요.
플래그가 없거나 잘못된 자리에 있어요. 열 번 중 아홉 번은 이게 원인이에요. experimental_use_rmcp_client = true는 config.toml의 가장 위쪽, 모든 [section]보다 위에 있어야 해요. 서버 블록 안에서는 아무 효과가 없어요.
키가 Codex의 환경에 없어요. Codex는 시작 시점에 bearer_token_env_var를 해석하기 때문에, 다른 터미널 탭에서 한 export나 .zshrc에는 추가했지만 소싱하지 않은 export는 보이지 않아요. 실행 직전 같은 셸에서 echo $BANKBRIDGE_API_KEY를 돌려보세요.
JSON을 붙여넣었어요. Claude Desktop이나 Cursor 문서의 스니펫은 TOML로 파싱되지 않아요. Codex가 설정 파일에 대해 불평하거나 조용히 무시한다면, 남아 있는 중괄호나 콜론을 찾아보세요.
Codex가 오래됐어요. 스트리밍 HTTP MCP 지원은 비교적 최근에 추가됐어요. npm install -g @openai/codex(또는 Homebrew로 설치했다면 brew upgrade codex)로 업그레이드하고 다시 시도해보세요.
연결한 뒤 무엇을 물어볼까
도구에 자연스럽게 매핑되는 몇 가지 시작점이에요:
내 정기 결제를 월 비용순으로 정렬해줘.
지난달에 어느 가맹점에서 가장 많이 썼어?
6월 수입과 지출을 비교해줘.
모든 것은 설계상 읽기 전용이에요. 돈을 옮기거나, 청구서를 내거나, 매매를 넣는 도구가 없기 때문에, 호기심 많은 에이전트가 만들 수 있는 피해 반경은 정확히 $0이에요. 그리고 키는 Codex 전용이 아니에요. 동일한 bbk_ 키가 Claude Code, Gemini CLI, Cursor, 그리고 저희가 문서화한 다른 MCP 호스트에서도 작동하니, 두 번째 에이전트를 연결하는 데는 약 30초면 충분해요.