콘텐츠로 이동

Codex CLI

Codex CLI 에 바른 MCP 등록하기

OpenAI Codex CLI 에 바른 MCP 서버를 연결하면, Codex 가 작업 중 직접 바른을 호출해 한국어 형태소 분석과 맞춤법 검사를 수행합니다.

준비물

  • 바른 API 키 — 발급과 사용량은 클라우드에서 사용하기를 참고하세요.
  • 엔드포인트 주소 — 바른 클라우드는 https://api.bareun.ai:443/mcp 입니다. 맞춤법 검사기를 직접 설치한 경우에는 그 서버 주소의 /mcp(예: http://localhost:5656/mcp)를 씁니다. MCP 는 맞춤법 검사기가 포함된 바른에서만 제공되며, 형태소 분석 전용 설치본에는 /mcp 가 없습니다.

등록 방법

Codex 는 MCP 설정을 ~/.codex/config.toml(또는 신뢰하는 프로젝트의 .codex/config.toml)에 둡니다. 서버마다 [mcp_servers.<이름>] 표를 추가하고, 원격 HTTP 서버는 url 을 지정합니다. 인증은 아래 두 가지 중 하나를 고르세요.

API 키를 환경변수에 두고 bearer_token_env_var 로 가리킵니다. 이 값은 자동으로 Authorization: Bearer ... 헤더로 전송됩니다.

[mcp_servers.bareun]
url = "https://api.bareun.ai:443/mcp"
bearer_token_env_var = "BAREUN_API_KEY"

실행 전에 환경변수를 설정합니다.

export BAREUN_API_KEY="발급받은_API_키"

http_headers 로 api-key 헤더를 직접 지정할 수도 있습니다.

[mcp_servers.bareun]
url = "https://api.bareun.ai:443/mcp"
http_headers = { "api-key" = "발급받은_API_키" }

구버전 Codex 라면

사용 중인 Codex 버전이 원격 HTTP MCP(url)를 지원하지 않으면, mcp-remote 브리지를 실행형(stdio)으로 등록할 수 있습니다(Node.js 필요).

[mcp_servers.bareun]
command = "npx"
args = ["-y", "mcp-remote", "https://api.bareun.ai:443/mcp", "--header", "api-key: 발급받은_API_키"]

연결 확인

  • 터미널에서 codex mcp list 로 등록된 서버를 확인합니다.
  • Codex 세션에서 "이 문장을 바른으로 교정해 줘" 처럼 요청하면 바른 도구 (analyze_syntax·tokenize·list_pos_tags·correct_grammar)를 호출합니다.

문제가 생기면

  • 서버가 안 붙나요? config.toml 의 표 이름([mcp_servers.bareun])과 url 끝의 /mcp 를 확인하세요. TOML 문법 오류가 없는지도 점검합니다.
  • 권한 오류(401)? bearer_token_env_var 가 가리키는 환경변수에 실제 키가 들어 있는지, 또는 http_headers 의 api-key 값이 올바른지 확인하세요.
  • 프로젝트 .codex/config.toml 이 무시되나요? 프로젝트 설정은 신뢰하는 프로젝트에서만 적용됩니다. 신뢰 설정을 확인하거나 사용자 설정(~/.codex/config.toml)을 쓰세요.

자주 묻는 질문

Q. bearer_token_env_var 와 http_headers 중 무엇을 써야 하나요?

키를 설정 파일에 직접 적고 싶지 않다면 환경변수 토큰(bearer_token_env_var)이 안전합니다. 바른은 Authorization: Bearer <키> 와 api-key 헤더 모두 받으므로 어느 쪽이든 동작합니다.

Q. Codex 가 원격 HTTP MCP 를 지원하지 않는 버전입니다.

mcp-remote 를 실행형(stdio)으로 등록하면 됩니다. command = "npx", args 에 mcp-remote 와 엔드포인트·헤더를 넣으세요(Node.js 필요).

도움이 되었나요?