MCP 코드 모드

AI 에이전트가 MCP 도구를 하나씩 호출하지 않고, 여러 도구를 부르는 짧은 코드를 써서 샌드박스에서 한 번에 실행하는 방식이다. 연결된 도구가 많거나 큰 데이터가 도구 사이를 오갈 때 토큰을 크게 줄이려고 쓴다.

이름은 Cloudflare가 2025년 9월에 처음 붙였고, Anthropic은 같은 방식을 'Code Execution with MCP'라는 이름으로 정리했다.

도구가 많을수록 많이 아낀다

일반 방식에서는 도구 정의가 컨텍스트를 차지하고, 회의록 같은 큰 데이터도 도구에서 도구로 넘어갈 때마다 모델을 한 번씩 거친다. 코드 모드에서는 모델이 필요한 도구만 찾아 읽은 뒤 반복이나 필터링을 코드로 처리하기 때문에, 중간 데이터는 모델에 들어가지 않는다.

위 사례는 Cloudflare, 아래 사례는 Anthropic이 직접 발표한 수치다.

반대로 도구가 10개도 안 되고 서로 이어서 호출할 일이 거의 없다면 오히려 손해다. 이럴 때는 일반 도구 호출을 그대로 쓰는 편이 낫다.

API 크기에 따라 서버 구성을 고른다

Cloudflare 문서는 두 가지 구성을 소개한다. API가 작아서 타입 선언이 도구 설명 안에 다 들어간다면 code 도구 하나만 열어 두면 된다. API가 크다면 search로 필요한 부분을 먼저 찾고 execute로 실행하는 두 단계 구성이 맞다.

샌드박스가 권한 검사까지 해 주지는 않는다

모델이 쓴 코드는 격리된 환경에서 돌아가고, 외부 네트워크 접근은 기본적으로 막혀 있다. 그래도 권한 확인과 승인은 도구 핸들러나 호스트 쪽에서 따로 해야 하고, 인증 정보가 코드나 결과에 드러나서도 안 된다. 셸로 이미 코드를 실행하는 에이전트에 코드 모드 서버를 또 붙이면 코드 안에서 또 코드를 돌리는 구조가 된다. 그러면 JSON 이스케이프가 두 번 일어나서 작은 모델일수록 헷갈리기 쉽다.

사람들은 주로 이렇게 쓴다