Codex MCP output_token_limit 설정과 잘림 원리
MCP 도구별 출력 토큰 예산을 조절 밸브로 표현한 AI 생성 대표 이미지
Codex MCP output_token_limit은 MCP 서버 전체가 아니라 개별 도구가 모델 대화 기록에 남길 출력 토큰 예산을 정하는 설정입니다. 2026년 9월 2일 기준 Codex 0.152.0에 포함됐으며, 큰 검색 결과나 로그가 세션의 판단 공간을 과도하게 차지하는 일을 도구 단위로 줄일 수 있습니다.
근거는 OpenAI Codex 0.152.0 릴리스, 변경 요청 #41421, 병합 커밋 f742dab입니다. 공개 설정 레퍼런스에는 전역 tool_output_token_limit가 보이지만 개별 도구 키는 아직 검색되지 않아, 아래 설명은 릴리스와 구현 변경을 기준으로 구분합니다.
- 개별 MCP 도구 출력 제한이 무엇을 제어하는지
- 출력이 잘리고 대화 기록에 보존되는 순서
config.toml에서 도구별 값을 넣는 위치- 전역 예산·플러그인 정책과 겹칠 때의 규칙
- 도구 성격에 맞춰 한도를 선택하고 검증하는 방법
이 값은 모델이 답변을 생성하는 최대 출력 토큰이 아닙니다. MCP 도구가 반환한 결과를 Codex가 대화 기록에 저장하고 다음 모델 호출에 전달할 때 적용하는 예산입니다.
공식 변경: OpenAI Codex PR #41421
1. Codex MCP output_token_limit은 무엇을 제한하나
서버가 아니라 도구 항목에 붙는 양의 정수입니다
#41421은 MCP 서버의 tools 아래 각 항목에 양수 output_token_limit를 추가했습니다. 같은 서버 안에서도 검색 도구와 상세 조회 도구에 서로 다른 예산을 줄 수 있다는 뜻입니다.
제한 대상은 도구 결과의 대화 기록입니다
Codex는 MCP 호출 결과를 모델 입력으로 넘기고 세션 기록에 남깁니다. 이 설정은 그 결과가 지나치게 길 때 기존 출력 잘림 로직에 도구별 예산을 전달합니다.
모델의 답변 길이와는 별개입니다
Responses API의 최대 생성 길이나 모델 컨텍스트 창을 늘리는 설정이 아닙니다. 이름이 비슷해도 max_output_tokens와 목적이 다릅니다.
2. MCP 도구의 긴 출력이 왜 문제가 되나
검색 결과와 로그는 작은 호출도 큰 본문을 만들 수 있습니다
리포지터리 검색, 브라우저 DOM, 관측 로그처럼 목록을 반환하는 도구는 호출 인수보다 결과가 훨씬 큽니다. 필요한 항목이 몇 개뿐이어도 원문 전체가 기록되면 이후 턴마다 함께 처리될 수 있습니다.
전역 한도 하나는 도구의 정보 밀도 차이를 반영하기 어렵습니다
짧은 상태 조회에는 작은 예산이 충분하지만, 코드 검색이나 정밀 문서 조회에는 더 큰 예산이 필요합니다. 모든 도구에 같은 값만 적용하면 한쪽은 불필요하게 길고 다른 쪽은 근거가 잘릴 수 있습니다.
세션 재개 때도 같은 결과를 유지해야 합니다
PR은 유효 MCP 출력 예산을 대화 기록 메타데이터에 함께 보존합니다. 도구 호출 직후에는 길었는데 재개 후 다른 기준으로 다시 잘리는 식의 불일치를 막기 위한 변경입니다.
장기 세션의 누적 문맥 문제는 기존 글 Codex 장기 세션 최적화의 구조와 개선 원리에서도 별도로 다뤘습니다.
3. 출력 잘림은 어떤 순서로 적용되나
도구 실행 뒤 결과 본문에 예산이 적용됩니다
구현은 MCP 도구가 반환한 텍스트 또는 콘텐츠 항목에 기존 토큰·바이트 기반 잘림 정책을 적용합니다. 성공 여부나 미디어 순서를 바꾸는 기능이 아니라, 결과 본문이 예산을 넘을 때 길이를 줄이는 단계입니다.
PostToolUse 훅 응답도 같은 유효 예산을 따릅니다
#41421 테스트 범위에는 도구 출력뿐 아니라 post-tool hook 응답도 포함됩니다. 앞선 0.151.0에서 추가된 MCP 결과 처리 훅과 연결해 보면, 확장이 결과를 바꾼 뒤에도 최종 도구별 예산이 유지됩니다.
훅의 위치와 오류 결과 처리 순서는 Codex 0.151.0의 MCP 도구 결과·플러그인 변화에서 확인할 수 있습니다.
재개한 세션은 저장된 유효 예산을 재사용합니다
커밋은 기록 메타데이터에 fallback token limit override를 저장합니다. 새 프로세스의 전역 설정이 달라져도 이미 저장된 해당 MCP 결과를 다른 길이로 재구성하지 않는 방향입니다.
4. config.toml에서 도구별 출력 한도를 설정하는 방법
MCP 서버의 tools 아래 정확한 도구 이름을 씁니다
다음은 docs 서버의 search 도구에 8,000 토큰을 지정한 운영 예시입니다. 숫자는 공식 권장값이 아니라 설명용이므로 실제 결과 크기를 측정해 조정해야 합니다.
[mcp_servers.docs]
command = "example-docs-mcp"
[mcp_servers.docs.tools.search]
output_token_limit = 80000이나 음수는 허용되는 값이 아닙니다
구현 타입은 0이 아닌 양의 정수입니다. 제한을 두지 않으려면 임의로 0을 넣기보다 해당 도구의 output_token_limit 항목을 생략하는 편이 설정 의미에 맞습니다.
공개 문서 반영 상태를 따로 확인합니다
OpenAI Codex 설정 레퍼런스에는 전역 tool_output_token_limit가 설명되어 있지만, 개별 도구의 output_token_limit 항목은 페이지 검색에서 확인되지 않았습니다. 새 버전 도입 사실은 릴리스 노트와 #41421에서 확인됩니다.
5. 전역 한도와 도구별 한도는 어떻게 다른가
전역 값은 일반 기본 예산입니다
tool_output_token_limit는 개별 도구·함수 출력이 기록에 저장될 때 사용하는 전역 예산입니다. 도구별 설정이 없는 출력에 공통 기준을 주고 싶을 때 적합합니다.
MCP 도구별 값은 해당 호출의 예산을 재정의합니다
#41421의 회귀 테스트는 특정 MCP 도구에 값이 있으면 그 도구의 예산이 전역값 대신 적용됨을 확인합니다. 따라서 전역값과 무조건 작은 값을 택한다고 해석하면 안 됩니다.
플러그인 정책과 사용자 정책이 겹치면 더 제한적인 값을 택합니다
PR 설명의 “most restrictive limit”은 플러그인이 제공한 도구 정책과 사용자 정책이 겹치는 경우입니다. 예를 들어 플러그인 한도가 4,000이고 사용자가 9,000을 넣으면 더 작은 4,000이 유효 한도가 되며, 승인 정책은 별도로 병합됩니다.
| 겹치는 설정 | 유효 동작 | 주의점 |
|---|---|---|
| 전역 + MCP 도구별 | 도구별 예산 적용 | 단순 최솟값 규칙으로 보지 않음 |
| 플러그인 + 사용자 도구별 | 더 제한적인 양의 값 | 승인 모드는 독립적으로 처리 |
| 도구별 값 없음 | 기존 기본·전역 정책 | 버전과 문서 상태 확인 |
6. 도구별 output_token_limit 값은 어떻게 고르나
도구가 반환하는 결과의 형태부터 분류합니다
검색 목록은 항목 수와 스니펫 길이가 중요하고, 로그는 오류 주변 구간이 중요하며, 정밀 조회는 원문 연속성이 중요합니다. 같은 토큰 수라도 보존해야 할 정보 구조가 다릅니다.
최솟값보다 실패 경계를 먼저 찾습니다
대표 질의를 실행해 정상 답변에 필요한 근거가 사라지는 지점을 찾은 뒤 여유를 둡니다. 너무 낮으면 식별자·오류 원인이 잘리고, 너무 높으면 무관한 결과가 대화 기록을 차지합니다.
한 번에 큰 값을 정하지 말고 관측하며 조정합니다
- 검색 도구: 필요한 상위 결과와 출처가 남는지 확인
- 로그 도구: 오류 앞뒤의 인과 구간이 보존되는지 확인
- 정밀 조회: 코드 블록이나 문서 절이 중간에서 끊기지 않는지 확인
- 목록 도구: 총계와 대표 항목을 함께 볼 수 있는지 확인
7. 너무 낮거나 높은 값에서 생기는 실패 조건
너무 낮으면 완전한 오류 근거가 남지 않습니다
스택 트레이스 끝부분, 검색 결과의 URL, 구조화된 JSON의 닫는 부분처럼 의미를 완성하는 정보가 잘릴 수 있습니다. 모델이 부족한 근거로 다시 같은 도구를 호출하면 호출 횟수만 늘어날 수 있습니다.
너무 높으면 도구별 설정의 목적이 약해집니다
큰 원문이 매번 대화 기록에 남으면 이후 판단에 필요한 지침과 최근 결정의 비중이 상대적으로 줄어듭니다. 비용이나 지연이 항상 같은 폭으로 늘어난다고 단정할 수는 없지만, 처리해야 할 입력이 커지는 방향은 분명합니다.
잘림 표식과 최종 답변 품질을 함께 봐야 합니다
잘림이 발생했다는 사실만으로 실패는 아닙니다. 필요한 근거가 남았는지, 모델이 추가 조회를 올바르게 요청하는지, 세션 재개 후 동일한 결과가 유지되는지를 함께 검증해야 합니다.
8. 적용 전후에 확인할 실무 체크리스트
버전과 정확한 도구 이름을 확인합니다
릴리스 노트에서 0.152.0 이상인지 확인하고, MCP 서버가 실제로 노출하는 도구 이름을 설정 테이블과 일치시킵니다. 이 환경에는 Codex CLI가 설치되어 있지 않아 로컬 재현 캡처는 만들지 않았습니다.
대표 질의로 전후 결과를 비교합니다
- 설정 전 원본 결과의 길이와 필요한 근거를 기록합니다.
- 도구별 한도를 넣고 같은 질의를 다시 실행합니다.
- 잘림 표식, 출처·식별자 보존, 후속 답변 정확도를 비교합니다.
- 세션을 재개해 해당 결과가 동일하게 유지되는지 확인합니다.
승인 정책과 출력 정책을 별도로 점검합니다
approval_mode는 도구 실행 허용을, output_token_limit는 실행 후 결과 길이를 다룹니다. 한쪽을 조정했다고 다른 쪽까지 바뀌었다고 가정하지 않습니다.
검색·로그처럼 결과가 큰 도구부터 적용하고, 근거 손실이 없는 가장 작은 값이 아니라 반복 호출까지 포함한 전체 작업 품질이 안정적인 값을 선택합니다.
9. Q&A와 정리
Q1. output_token_limit 값을 쓰면 MCP 서버 출력 자체가 줄어드나요?
서버가 생성하는 원본을 바꾸는 설정으로 설명되어 있지 않습니다. Codex가 결과를 받아 대화 기록과 후속 모델 입력에 반영하는 단계의 예산입니다.
Q2. 모든 MCP 도구에 같은 값을 넣어야 하나요?
그럴 필요가 없습니다. 이 기능의 목적은 도구별 정보량 차이를 반영하는 것이므로 결과가 큰 도구부터 선택적으로 적용할 수 있습니다.
Q3. 0을 넣으면 제한이 해제되나요?
아닙니다. 구현은 양의 0이 아닌 정수를 요구하므로, 도구별 설정을 사용하지 않으려면 항목을 생략합니다.
Q4. 플러그인 한도보다 사용자 값을 크게 설정할 수 있나요?
입력은 가능해도 정책이 겹치면 더 제한적인 값이 유효합니다. 사용자 설정으로 플러그인의 낮은 제한을 넓히는 용도로 보기는 어렵습니다.
Q5. 공식 설정 문서에 바로 보이지 않으면 기능을 쓰면 안 되나요?
릴리스와 병합 코드는 기능 존재를 확인해 주지만, 배포 버전과 스키마 지원 여부는 별도 확인이 필요합니다. 문서가 갱신되면 키 설명과 예시를 다시 대조하는 편이 안전합니다.
핵심은 큰 MCP 결과를 무조건 줄이는 것이 아니라 도구마다 필요한 증거를 남기는 예산을 정하는 것입니다. 버전·도구 이름·잘림 결과를 같은 대표 질의로 검증하면 설정 효과를 분리해 볼 수 있습니다.
참고 자료
공식 릴리스와 구현 변경
공식 설정 문서
'Codex' 카테고리의 다른 글
| Codex GPT-5.4 지원 종료, 8월 31일 무엇을 바꿔야 할까? (0) | 2026.08.31 |
|---|---|
| Codex 0.151.0 업데이트: MCP 도구 결과·플러그인 변화 (0) | 2026.08.31 |
| loveholidays Codex 도입, 코드 변경 79%는 무엇을 뜻하나? (0) | 2026.08.28 |
| Codex Multi-Agent v2 모델 분담 실전 가이드 (0) | 2026.08.16 |
| Codex 장기 세션 최적화 — 느려지는 구조와 개선 원리 (0) | 2026.08.15 |
