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 필요).