mcptoon: Token-Efficient MCP CLI Client

mcptoon을 통한 MCP 토큰 오버헤드 감소

mcptoon은 Model Context Protocol (MCP)과 관련된 토큰 비용을 최소화하도록 설계된 크로스 플랫폼 CLI 클라이언트입니다. 표준 JSON 응답을 TOON(Token-Optimized Object Notation)이라고 불리는 독자적인 압축 표기법으로 대체함으로써, mcptoon은 도구 탐색(tool discovery) 비용을 최대 97%까지, 도구 결과 오버헤드를 40-60%까지 줄일 수 있다고 주장합니다.

문제점: JSON 구문 팽창

표준 MCP 지원 대화는 실제 데이터보다 구조적 구문에 상당한 양의 토큰을 소비하는 경우가 많습니다. 프로젝트 문서에 따르면, 도구 목록을 나열하기 위해 5개의 MCP 서버에 연결하는 데 약 10,000개의 JSON 토큰이 소모될 수 있습니다. 에이전트가 여러 도구를 호출할 때 결과가 장황한 JSON 구조(예: {"content":[{"type":"text","text":"..."}]})로 래핑되어, AI가 실제 정보를 처리하기 시작하기도 전에 128K 컨텍스트 창의 30-55%를 소비할 수 있습니다.

해결책: TOON (Token-Optimized Object Notation)

mcptoon은 stdio 또는 HTTP를 통해 MCP 서버에 연결하고 JSON 출력을 TOON으로 변환합니다. 이 표기법은 문자 수와 토큰 수를 줄이기 위해 특정 치환을 사용합니다:

JSON	TOON	로직
`{"name":"search","count":3}`	`name:search	count:3`
`[1, 2, 3]`	`1 2 3`	공백이 대괄호와 쉼표를 대체
`true` / `false`	`T` / `F`	단일 문자 대체
`null`	`∅`	단일 기호 대체
`"line1\nline2"`	`line1↲line2`	특수 기호가 이스케이프 시퀀스를 대체
`{"a":{"b":[1,2]}}`	`a:b:1_2`	재귀적 압축

성능 비교

작업	JSON 토큰	mcptoon 토큰	절감률
도구 탐색 (96개 도구)	~2,000	~60	97%
도구 결과 (구조화된 데이터)	~800	~350	56%
도구 결과 (원시 HTML/텍스트)	~1,000	~900	10%

통합 및 호환성

mcptoon은 순수 Python (3.10+)으로 작성되었으며 외부 종속성이 없는 CLI 도구입니다. Claude Code, Cursor, Codex, OpenCode를 포함하여 쉘 명령을 실행할 수 있는 모든 AI 에이전트와 호환됩니다.

배포 예시

Claude Code: 사용자는 SKILL.md 파일에 mcptoon 명령어를 작성하고 MCPTOON_AGENT_TYPE=claude를 설정하여 --toon 출력 형식을 자동으로 선택할 수 있습니다.
Cursor: 도구를 .cursorrules에 추가할 수 있습니다.
Codex (OpenAI): 도구 목록을 위해 mcptoon manifest --toon을 사용하도록 AGENTS.md 또는 시스템 프롬프트에 지침을 추가할 수 있습니다.

주요 기능 및 안전성

통합 설정: MCP 서버는 ~/.mcptoon/config.json에 한 번만 설정하면 여러 에이전트가 동일한 도구 세트를 공유할 수 있습니다.
안전 차단: 클라이언트는 --destructive 플래그가 전달되지 않는 한 위험한 패턴(예: delete, drop, purge)과 일치하는 작업을 차단합니다.
사용량 추적: 총 호출 횟수, 성공률 및 예상 토큰 절감액에 대한 로컬 추적 데이터가 ~/.cache/mcptoon/usage.json에 저장됩니다.
스키마 캐싱: 탐색 오버헤드를 더욱 줄이기 위해 5분 TTL을 가진 스키마 캐시를 포함합니다.

기술 커뮤니티 비평

이 프로젝트는 토큰 절감을 강조하지만, Hacker News 커뮤니티의 여러 개발자들은 TOON 표기법의 실제 효능에 대해 우려를 제기했습니다:

토큰화 vs 문자 수: 비판론자들은 저자가 문자 수와 토큰 수를 혼동하고 있을 수 있다고 주장합니다. 예를 들어, 사용자들은 true/false와 null이 현대적인 토크나이저에서 종종 단일 토큰이라는 점을 지적했습니다. 이는 T/F 또는 ∅로 대체하는 것이 이득이 없거나, 비 ASCII 유니코드 기호 사용으로 인해 오히려 토큰 수를 증가시킬 수 있음을 의미합니다.
정보 손실: 일부 사용자는 도구 이름만 반환하는 --compact 모드가 중요한 설명과 입력 스키마를 제거하여, 잠재적으로 LLM의 환각(hallucination)이나 잘못된 도구 호출을 유발할 수 있다고 지적했습니다.
대안적 접근 방식: 일부 개발자들은 인자 환각을 방지하기 위해 도구 이름만 나열하는 것보다 인자와 함께 도구 이름을 반환하는 것(예: search_web(query))이 더 효과적이라고 제안했습니다.

"제 생각에 이러한 선택 중 일부는... 저자가 토큰화가 어떻게 작동하는지 조사하지 않았음을 보여줍니다. 토큰화는 블랙박스가 아니며, 토크나이저를 실행하여 확인할 수 있습니다."

빠른 시작 가이드

# 설치
pip install mcptoon

# 초기화 및 서버 추가
mcptoon init
mcptoon add fetch --stdio npx -y @modelcontextprotocol/server-fetch

# TOON 형식으로 도구 목록 보기
mcptoon manifest --toon

# 도구 호출
mcptoon call fetch fetch '{"url":"https://example.com"}' --toon