mcptoon

MCP トークン最適化、ツールの発見、コンテキスト圧縮 — MCP ツールとエージェントスキルのためのゼロ設定 CLI

スキルを1,000個、MCP ツールを1,000個ローカルにインストールしても、コンテキストの過剰消費を心配する必要はありません。
MCP トークン最適化のための、依存関係ゼロのMCP CLIおよびMCP クライアントです。簡潔な名前インデックスによるツールの発見とコンテキスト圧縮により、ツールのコンテキストを約90％削減（255個のツールでは99.2％）し、スキーマがコンテキストウィンドウに入るのを防ぎます。103以上のデスクトップエージェントと CLI エージェントで設定は不要です。

🌐 公式サイト · 🧮 30秒でわかるトークンコスト計算ツール · 🇨🇳 中国語ドキュメント · 📖 開発者向けドキュメント

_{合成された255ツールのサンプルに懐疑的ですか？ 実機で測定した、実在する公開 MCP サーバー7つ（ツール209個）の結果はこちらです → — 640,606から905トークンへ（−99.86％）。または、独自のカタログで mcptoon bench を実行してください。}

https://github.com/user-attachments/assets/0272d3a8-c74f-428d-8559-fbf804ce0685

① 💥 ツール、スキル、ドキュメントがコンテキストを圧迫しているのに、これ以上追加するのが不安ですか？ 好きなだけ追加できます。ツールスキーマは72k → 581 tokensに。 ツール −99.2% · スキル −99.99% · ドキュメントは質問ごとに40k→17k

② 🧩 複数のエージェントを使っていて、JSON 設定とスキルの管理が面倒ですか？ これはネイティブ CLIです。シェルコマンドを実行できるエージェントなら、すべての機能を利用できます。MCP サーバーも設定も不要です。GUI クライアントも含め、syncで対応します（103+）。 JSON の編集も再起動も不要

③ 🔍 17,000+もあるのは知っているけれど、どれが自分に合うかわかりませんか？ まず、すでにあるサーバーを検出します（再インストール不要）。その後、普通の言葉で残りを検索でき、その場でインストールして呼び出せます。 mcptoon discover → search → call

_{ほかにも、OpenAPI / GraphQL パススルー · OAuth · MCP リソースとプロンプト · 接続の保存 · コードサンドボックスに対応 — すべてのコマンドを見る。}

pip install mcptoon && mcptoon quickstart — 534KB、依存関係ゼロ、設定不要。

_{常に最新の状態を保てます。新しいバージョンがあると通知し、mcptoon upgradeを実行すれば1つのコマンドで更新できます。}

🚀 クイックスタート（方法を選択）

# Ask the built-in skill anytime:
"Load /mcptoon skill and check what MCP tools I currently have."
"Help me find an MCP tool that converts HTML to PDF and call it."
"The tool output was truncated, retrieve the full original copy."
"How many tokens did mcptoon save for me today?"
"Doctor self-check: are all my MCP servers connected properly?"

# 1. Install (zero dependencies, 534KB)
pip install mcptoon

# 2. One command: detect MCP servers & auto-configure agents
# (Also self-installs `/mcptoon` skill into all detected agents)
mcptoon quickstart

# 3. View compact tool catalog (-99.2% tokens)
mcptoon manifest

# 4. Route tasks to skills or doc chapters (<5ms)
mcptoon skills resolve "write git commit message"
mcptoon docs resolve "how does release gating work"

本当に何か節約できていますか？ 新規インストール後、mcptoon は directモードのまま、つまりインストール済みでもエージェントには接続されず、何も節約できていない場合があります。どのモードが最も低コストですか？を参照するか、mcptoon modeを実行してください。

⚡ 主な機能の概要

_{フラグを含むすべてのコマンドは、すべてのコマンドをご覧ください。}

mcptoon を選ぶ理由

すべての MCP エージェント（Claude Code、Cursor、Codex など）は、作業を始める前にすべてのツールとスキルの説明全体をコンテキストウィンドウに読み込み、さらに毎ターン再送信します。255 個のツールでは71,929 トークンに達します。最初の質問をする前に、説明だけで 128K のウィンドウの半分以上を消費します。

トークン削減の仕組み

mcptoon は説明をコンテキストではなくディスク上に保持し、代わりにエージェントにコンパクトなビューを渡します。

• 完全なスキーマではなく、名前のインデックスを使います。 ツールを選ぶのに必要なのは名前だけです。255 個のツールが**581 トークン（−99.2%）**になります。完全なスキーマは、ツールが実際に呼び出されたときに限り、mcptoon inspect でオンデマンド取得されます。
• スキルも同様です。 常駐するポインター 1 つ（39 トークン）とルックアップ 1 回（791 トークン）で、すべての SKILL.md を完全な形で読み込む必要がなくなります。**1,572,330 → 39 + 791（−99.99%）**です。
• 結果も同様です。 --toon を使うと、ツールの結果が標準 TOON として再エンコードされます。 複数の種類を含む結果サンプルでは**5.7%小さくなりました。結果の形状によって1.8%～48.6%**の差があり、レコードのリストはほとんど縮まず、単一のレコードは半分になります。一律に 34% 縮小するわけではありません。assets/benchmark_results.json をご覧ください。

情報が失われることはありません。完全なスキーマもスキルの全文も、コマンド 1 つですぐに取得できます。節約されるのはコンテキストウィンドウだけです。

mcptoon は534KB、依存関係ゼロのネイティブ CLIで、コンピューター上のすべての MCP ツールとエージェントスキルを管理し、設定を自分で書くことなく、すべてのエージェント間で共有します。

私たちだけが言っているのではありません

これらの数値は私たちが測定したものですが、「すべてのツールスキーマをコンテキストに読み込むのはコストがかかる」という主張をしているのは、私たちだけではありません。

• Anthropic のエンジニアリング記事 — ツールスキーマがコンテキストウィンドウを埋め尽くすのは実際にコストとなります。一例では 150,000 トークンから 2,000 トークンに削減されています。
• Firecrawl のベンチマーク — 同じタスクにかかったトークン数は、CLI 経由では 1,365、MCP 経由では 44,026（32 倍）でした。
• Scalekit のベンチマーク — CLI は 10～32 倍低コストで、信頼性は 100% です。MCP の信頼性は 72% でした。
• MCP-Zero（arXiv:2506.01056） — ツール数にかかわらずコストがほぼ一定となる、オンデマンドのツール取得方式です。

mcptoon は今すぐ使えます。シェルを実行できるあらゆるエージェントに対応し、対応している主要な GUI クライアントには接続用の 1 行を自動で書き込みます。

2 つの使い方

あなたの環境で数値を測定しましょう。pip install mcptoon && mcptoon bench を実行すると、以下の固定された 255 ツールのサンプルではなく、あなた自身のカタログについて報告されます（サンプルの測定方法はdocs/tiktoken-benchmarks.mdに記載されています）。

スキルも同じ仕組みです。SKILL.md のテキスト 1,572,330 トークンが、常駐分 39 ＋ ルックアップごとに 791（−99.99%）になります。呼び出し結果は --toon を使うとさらに**約 6%**縮小します（結果の形状によって異なります）。

パス 1 · AI ツールを使うだけの方

Claude、Codex、Cursor、Windsurf、Cline、VS Code Copilot、そして ほかにも 97 種（103 種の一覧 →）のデスクトップ AI をお使いの方。ツールや スキルを追加するには、これまではエージェントの JSON を手作業で編集する必要がありました。mcptoon を使えば、その手順は不要です。

1. 一度インストールします。

   pip install mcptoon && mcptoon quickstart
   

   quickstart が MCP サーバーを検出して設定を書き込み、検出したすべてのエージェントに mcptoon を登録します。 （quickstart を省略しても、最初に実行するコマンドが自動的に修復します。マシンごとに一度、各エージェントに mcptoon 専用のスキルをインストールし、スキルインデックスを作成します。）

2. ツールとスキルを一か所で追加します。エージェントごとに追加するのではなく、ここで管理できます。

   mcptoon install --search github     # find and install any MCP server
   mcptoon skills search "make a PDF"  # find a skill by what it does
   

3. どのエージェントからでも使えます。 エージェントはほかのコマンドと同じように mcptoon を実行します。設定も再起動も不要です。すべての AI エージェントに対応をご覧ください。

すぐに始めたい方へ。 組み込みのスターターパック essentials、web-research、code-review、docs を使えば、コマンド一つで実用的なツールセットを用意できます。

mcptoon install --pack essentials

パス 2 · MCP／エージェントを使って開発する方

mcptoon は、スクリプトで処理できる出力を備えたシンプルな CLI で、必要に応じて MCP エンドポイントも利用できます。

mcptoon manifest --format json      # machine-readable tool index
mcptoon call <server> <tool> '{}'   # call any tool, JSON or --toon output
mcptoon serve                       # expose every configured server behind one MCP endpoint

• 安定した出力 — デフォルトは JSON です。結果を小さくするには --toon を使用します（結果の形状に依存し、混合サンプルでは 5.7%）。標準の MCP JSON をエクスポートするには --format mcp を使用します。
• mcptoon serve — プロキシを必要とするクライアント向けに、stdio または HTTP、接続プーリング、エージェントごとのキーに対応します。
• 依存関係ゼロ — Python 標準ライブラリのみを使用するため、CI、コンテナ、エアギャップ環境など、あらゆる環境に導入できます。

詳細なリファレンス：DEVELOPERS.md とすべてのコマンド。

目次

• mcptoon を選ぶ理由
• トークンを節約する仕組み
• これは私たちだけの主張ではありません
• 利用方法は 2 通り
• パス 1 · AI ツールを使うだけの方
• パス 2 · MCP／エージェントを使って開発する方
• 30 秒で使い始める
• できること
• ツールの入手先
• 3 種類のコスト
• インストール
• すべての AI エージェントに対応 — 103 クライアント（CLI 42 種 · serve 61 種）
• プロキシではなく CLI を使う理由
• 最もコストが低いモードは？
• すべてのコマンド
• 信頼と安全性
• クレジットと参考資料
• コントリビュート
• トラブルシューティングと FAQ
• ライセンス

30秒で起動

pip install mcptoon                          # pure stdlib, 534KB, zero dependencies

# One command: find your MCP servers, write your config, register the gateway
# in every agent you have, and show you what it found:
mcptoon quickstart

# See every tool available (names-only by default; 255 tools cost 581 tokens):
mcptoon manifest

# Call a tool (JSON output by default; add --toon to save more).
# `everything` is only present if you already had it; otherwise add the built-in
# zero-dependency demo server first (no Node, no network) and call that:
mcptoon add demo --stdio python -m mcptoon demo-server
mcptoon call demo echo_message '{"message":"hi"}'

quickstart は、mcptoon を見えるようにする役割も担います。各エージェントの設定に、予約済みサーバー mcptoon として mcptoon serve を書き込み、エージェントが mcptoon 自体を認識できるようにします。すでに同期済みの場合は、mcptoon sync --self で再登録してください（通常の mcptoon sync ではサーバーのみが書き込まれます）。状態はいつでも mcptoon status で確認できます。

利用方法は2つありますが、どちらかを選ぶ必要はありません。 mcptoon はまずCLIとして使うものです。シェルを使えるエージェントは mcptoon コマンドを実行でき、これが最も低コストな方法です。スキーマがコンテキストに入ることはありません。quickstart は、mcptoon 独自のMCPエントリー（mcptoon serve）も、対応する各エージェントに登録します。そのため、MCP サーバーしか認識できないクライアントからも、ツールにアクセスできます。MCPエントリーは compact モードで動作し、上流ツールの一覧をモデルのコンテキストに含めず、代わりに mcptoon_manifest → inspect → call に送ります。mcptoon status では、両方の台帳を確認できます。

そして、すべて元に戻せます。 インストール時にゲートウェイが登録され、デフォルトでは quickstart がさらに引き継ぎを行います。既存のサーバーをゲートウェイ経由でルーティングし、直接登録されたエントリーを削除します（この手順を行わないと、エージェントには同じツールが直接とゲートウェイ経由で二重に表示され、コストが下がるどころか上がります）。この手順は一覧に表示され、確認を求められ、元に戻すこともできます。**mcptoon restore はゲートウェイのエントリーを削除し、サーバーを元の場所にそのまま戻します。**その後に設定へ追加した内容には手を加えません。より簡易な切り替えには mcptoon off を使います。ゲートウェイのエントリーだけを削除し、サーバーは元の場所に残します。どちらの操作も --dry でプレビューでき、mcptoon uninstall --dry では削除計画全体を確認できます（削除する内容を先に正確に表示します）。

まだインストールしたくない場合は、動作を試してみましょう（Node が必要です）。

uvx mcptoon demo --quick

公式の「everything」リファレンスサーバーを起動し、1つのツールを呼び出して、トークンの計算結果を画面に表示します。APIキーも、自分のサーバーも、ディスクへの書き込みも必要ありません。

機能

ツール：必要に応じてスキーマを取得

完全なスキーマは名前のインデックスに圧縮されます。必要なツールがあるときは、mcptoon inspect で実際のパラメーターを取得し、その後 call で実行します。毎ターンではなく、一覧の分だけのコストで済みます。

スキル：常駐するポインターを1つ

カタログ全体を読み込む必要はもうありません。1行のポインターだけが常駐し（39トークン）、1回の検索で最も関連性の高いスキルを取得できます（791トークン）。ビューはリンクです（Windowsでは管理者権限不要のジャンクション）。そのため、元の場所で1回編集するだけでどこにでも反映され、別のコピーが古くなることもありません。

一度インストールすれば、どこでも共有

mcptoon を一度インストールすれば、マシン上のすべてのAIがすべてのツールとスキルを利用できます。後から追加したものもすぐに使えます。エージェントの再起動も、エージェントごとのJSONも不要です。

好きな方法でツールを追加

mcptoon install brave-search --npm @modelcontextprotocol/server-brave-search
mcptoon install my-tool --pip mcp-my-tool
mcptoon install remote-api --url https://example.com/mcp
mcptoon add my-server --stdio npx -y @any/mcp-package
mcptoon install --list                       # see what's installed
mcptoon install --remove brave-search        # uninstall one

npm、pip、HTTP の各サーバーにつき、コマンドは1つです。または、すでにあるものを mcptoon にスキャンさせることもできます：mcptoon discover。

トークンが必要なリモートサーバーは、環境変数からトークンを読み取るため、認証情報がディスクに書き込まれることはありません。

mcptoon install remote-api --url https://example.com/mcp \
  --header 'Authorization: Bearer ${BAIZHI_TOKEN}'   # BAIZHI_TOKEN set in your environment

${NAME} はリクエスト時に解決されるため、設定、生成されたハンドラー、すべてのログにはテンプレートが保持されます。変数を更新すれば、再インストールなしで次の呼び出しから新しい値が使われます。変数が存在しないか空の場合は、その名前を明示してエラーになり、空のヘッダーとして処理されることはありません。

ツールの入手元 — 17,000 件以上を検索し、1 つのコマンドでインストール

新しいマシンで最初に考えるのは、「トークンをどう節約するか」ではなく、「そもそもどのツールを使いたいか」です。以前は、GitHub で mcpServers のスニペットを探し、JSON に手作業でコピーするのが一般的でした。

mcptoon にはツールが同梱されておらず、カタログも含まれていません。上流のレジストリに問い合わせるため、必要なものをそのまま検索できます。

mcptoon install --search github     # search, list only — nothing installed
mcptoon install --search postgres
mcptoon install github              # search and install

検索結果には ✓（レジストリで検証済み）、種類のタグ（npm / pypi / hosted / remote）、呼び出し回数が表示されます。データは 2 つの上流からリアルタイムで取得され、保存されることはありません。

何も同梱されていない理由： 組み込みリストを更新するにはリリースが必要になり、他者のソースがサプライチェーンに取り込まれることになります。mcptoon が保存するのはポインターだけです。検索結果は自身の ~/.mcptoon/config.json に 1 行追加され、サードパーティーのソースが mcptoon 内に取り込まれることはありません。

その後、すべてのエージェントに配布できます。

mcptoon sync          # push the new tools to every detected agent
mcptoon manifest      # see every tool (name index, the cheapest view)

検索結果の見方： インデックスには、公式の @modelcontextprotocol/* サーバーと、個人が公開したパッケージが混在しています。✓ はレジストリによってエントリーが検証済みであることを示します。認証情報を渡す前にソースを確認してください。

スキルについて： skills search <query> はオープンスキルインデックス（skills.sh）を検索します。機能からスキルを探し、skills add <git-url> でインストールできます。mcptoon がインストールするのは指定したリポジトリです。カタログはオープンエコシステムそのものです。

スターターパック： ツールを 1 つずつ選びたくない場合は、4 つの組み込みパック（essentials、web-research、code-review、docs）から選べます。それぞれ、いくつかのツールとすぐに使えるプロンプトがまとまっています。mcptoon install --packs で一覧を表示し、mcptoon install --pack essentials でインストールできます。調査用の 2 つのパックには API キーは不要です。

3 種類のコストと、混同してはいけない理由

mcptoon は 3 つの異なる場面でトークンを節約します。それぞれの数値を比較しても意味はありません。

以下の数値は、規模の異なる 3 つのカタログから算出されています。合成した 255 ツールのサンプル（固定の主なベンチマーク値）、1,109 ツールを登録したマシン、およびお使いのマシンのカタログです。一方のパーセンテージと、もう一方のトークン数を比較しないでください。各表に測定対象のカタログが記載されています。

「どれだけ節約できるか」の見方は 2 通りあり、それぞれ異なる問いに答えます。ゲートウェイの数値（完全なスキーマと、エージェントがデフォルトの compact 露出で実際に読み込む情報との比較）は、mcptoon を導入することで得られる効果であり、主な指標として妥当です（カタログの規模に応じて変わり、ツールが多いほど削減量も大きくなります）。スリムスキーマの数値（同じツールの説明を簡潔にした場合）は、より小さな二次的な効果（88.5%）で、manifest --slim によって得られます。mcptoon status は同じ測定結果から両方を並べて表示するため、数値が食い違うことはありません。

コスト 1 · ツールの検出（manifest）：デフォルトで 99.2% 削減

フラグを指定しない mcptoon manifest は、この階層です。さらに情報が必要な場合は、--slim（名前とパラメーターの型、8,282 トークン、−88.5%）または --full（完全なスキーマ）を指定します。

コスト 2 · 呼び出し結果（call）：任意、--toon で約 6% 削減

このコストが発生するのは、ツールが結果を返した後です。mcptoon call はデフォルトで JSON を出力し、デフォルトでは何も節約しません。結果を短縮するには --toon を追加します。

請求額 3・スキルカタログ（skills）：1,572,330 → 常駐 39 + 参照ごとに 791

mcptoon skills manifest                      # 39 tokens, resident
mcptoon skills resolve "make a PDF" --k 5    # 791 tokens, the 5 most relevant

この README を作成したマシンで、3 つすべてを 1 つの表にまとめました。

固定の主要ベンチマークは、50 台のサーバーにまたがる 255 個のツールの合成サンプルを対象にしたものです。 tiktoken cl100k_base を使用しています。お使いのカタログの数値ではありません。ご自身の数値は mcptoon status を実行して確認してください。

mcptoon bench でご自身のカタログを測定できます（固定サンプルではなく、お使いのツールが報告されます）。 上記の 3 形式の正確な表も再現できます。クローンは不要です。

mcptoon manifest                 # populate the schema cache
python -m mcptoon.bench_tokens   # the same JSON / --slim / --compact counts, your tools

測定方法と基準： docs/tiktoken-benchmarks.md。

インストール

pip install mcptoon

Linux（Debian/Ubuntu 23.04 以降、および PEP 668 に準拠するすべてのディストリビューション）、ならびに macOS の Homebrew Python。 その環境では、システム Python への通常の pip install は error: externally-managed-environment で拒否されます。これはディストリビューションがシステムを保護しているためで、 mcptoon の問題ではありません。代わりに、適切な方法でインストールしてください。

pipx install mcptoon     # CLI を分離してインストールします。推奨
# または、管理下の仮想環境にインストールします。
python3 -m venv ~/.mcptoon-venv && ~/.mcptoon-venv/bin/pip install mcptoon

pip install --break-system-packages mcptoon でも動作しますが、システム Python に書き込みます。 pipx または仮想環境をお勧めします。Windows では pip install mcptoon をそのまま実行できます。

# Run without installing (needs Node)
uvx mcptoon demo --quick

# Isolated CLI install (avoids the PEP 668 error on Linux / Homebrew Python)
pipx install mcptoon

# From source (for development)
git clone https://github.com/activeing123/mcptoon.git
cd mcptoon
pip install -e . --no-build-isolation

# Claude Code plugin
/plugin marketplace add activeing123/mcptoon

Nix

numtide/llm-agents.nix によってパッケージ化されています。ボットが PyPI のすべてのリリースを追跡するため、flake のバージョンが手動更新待ちで古くなることはありません。

# Run straight from the flake, no install step
nix run github:numtide/llm-agents.nix#mcptoon -- --help

プラグインとスキルはどちらも sudosubin/agents.nix を通じて、 pkgs.agent-plugins.github.activeing123.mcptoon.<plugin-name> および pkgs.agent-skills.github.activeing123.mcptoon.<skill-name> として提供されています。

すべての AI エージェントで動作します

mcptoon がエージェントに到達する方法は 2 通りあり、以下のクライアントはすべてどちらかに当てはまります。 選ぶ必要はありません。quickstart が両方を登録し、各ホストが利用可能な方法を使います。

• CLI 経由 — エージェントが mcptoon を直接実行します。 シェルを利用できるもの（CLI エージェントやターミナルを備えたコーディング IDE）なら、設定は一切不要です。mcptoon call、mcptoon search、mcptoon skills resolve を実行します。ホスト側には何も書き込まれません。
• serve 経由 — クライアントがシェルを実行できません。 チャットアプリや GUI は代わりに MCP をマウントするため、エントリを 1 つ取得します。単一の MCP サーバーとしての mcptoon serve です。1 行、1 か所です。

市場を網羅。 103 のクライアントを対象としています。awesome-mcp-clients に加え、同一覧より後に公開されたコーディングエージェントのベンダードキュメントから収集しました。開発者向けの ライブラリ（mcp-agent、mcp-client-go）は、ユーザーが実行するものではないため除外しています。証拠はクライアントごとに確認しており、推測ではなく、検証した内容を示しています。

CLI 経由 — 42 クライアント、設定不要（mcptoon を直接実行します）：

AdaL · Aider · Amazon Q Developer · auggie · Autohand Code CLI · Claude Code · Claude Code Open · ClaudeMind · Cline · Codex · ContextKit · Continue · Copilot CLI · Copilot-MCP · Crush · Cursor · Dexto · Dolphin-MCP · Enola · Gemini CLI · Goose · JDBCX · Junie · KiloCode · Kiro · McPico · MCPOmni Connect · mistral-vibe · Nerve · Octomind · opencode · OpenHands · PraisonAI · Qwen Code · Roo Code · Slack MCP Client · SwarmClaw · Trae · VS Code GitHub Copilot · Warp · Windsurf · Zed

serve 経由 — 61 クライアント、mcptoon serve のエントリが 1 つ（シェルがないため、MCP をマウントします）：

5ire · Agent Bridge · Agent-cli · AgentOne · AIaW · Ano · AnythingLLM · Argo-LocalAI · askit-mcp · AstrBot · BoltAI · BrowseWiz · Canvas MCP Client · CarrotAI · Chainlit · ChatMCP · Cherry Studio · Claude Desktop · console-chat-gpt · DeepChat · DocsGPT · eechat · Enconvo · Fastchat MCP · FLUJO · Glue · HyperChat · kibitz · Klavis AI · LangBot · LibreChat · LobeHub · Lutra · MCP Chatbot · MCP CLI client · MCP Playground · MCP Simple Slackbot · MCP SuperAssistant · MCPCLIHost · MCPHost · Memex · MindPal · NextChat · OpenClaw · oterm · Qordinate · Runbear · SeekChat · Simple AI · Superinterface · Tambo · Taskade · Tester MCP Client · Tiles Notebook · Tome · Vercade · WhatsMCP · Witsy · y-cli · Yume · Zin-MCP-Client

証拠の状況 — sync --self は、各ホストのドキュメントに照らして検証済みの 12 ホストに接続行を書き込みます。上記のその他のホストは、ホスト固有のファイルを使わずに CLI または mcptoon serve 経由で接続するため、ホストごとに検証する項目はありません。

mcptoon がホストごとに書き込む内容

mcptoon はCLI ツールです。常駐型のプロキシやサービスではなく、クライアントライブラリでもありません。エージェントが上流の MCP サーバーと直接通信することはありません。mcptoon コマンドを実行するか、mcptoon 独自の MCP エントリ（mcptoon serve）を経由してアクセスします。設定ファイルを使うホストでは、実際に次の場所に書き込まれます。

# Agent needs GitHub access mid-task? It just runs:
mcptoon add github --url https://api.githubcopilot.com/mcp/
# Done. No JSON editing. No restart. No lost context.

もう一方の方法である mcptoon serve では、設定済みのすべてのサーバーを1つの MCP エンドポイントの背後で実行します。接続プーリングとエージェントごとのキーを備えており、プロキシを必要とするクライアント向けです。どちらか一方を選ぶ必要はありません。CLI が引き続き主要な接続方法となり、ホストが対応している場合はブリッジも併せて設定されます。

プロキシではなく CLI を選ぶ理由

MCP の前提では、各機能はエージェントが接続できるよう設定しなければならない「サーバー」です。そのため、新しいツールを1つ追加するたびに、エージェントごとに形式の異なる JSON を編集し、すべてを再起動して、各エージェントでスキーマのコストを全額負担することになります。

コマンドラインは、すべてのエージェントがすでに備えている唯一のインターフェースです。また、mcptoon が何かをする前から、CLI という形式そのもののほうが測定可能なほど低コストです。

• Firecrawl：同じタスクのコストは CLI で 1,365 トークン、MCP で 44,026 トークン — 32 倍
• Scalekit：CLI は MCP の 72％に対して、10～32 倍低コストで、信頼性は 100％

プロキシ形式も利用できます。mcptoon serve は設定済みのすべてのサーバーを1つの MCP エンドポイントの背後に配置します。また、quickstart では CLI と併せて設定されるため、どちらか一方を選ぶ必要はありません。このセクションでは、切り替えが必要な選択肢ではなく、mcptoon の基本となる設計について説明します。

どのモードが最も低コストですか？

mcptoon がエージェントにツールを渡す方法は3つあり、コストはそれぞれ大きく異なります。最も低コストなのは1つだけで、新規インストール時の初期状態ではありません。以下のトークン数は255個のツールを使ったサンプルに基づいています。実際のカタログの数値は異なります。mcptoon mode で確認できます。

CLI が最も低コストなのは、待機中のコストがゼロだからです。 ツールを使わないターンでは何もかからず、使うターンでも数百トークンしかかかりません。serve はそれに次ぐ低コストで、毎ターン少額の固定コストがかかります。mcptoon をインストールしてもエージェントに接続していない場合に発生するのが direct のコストです。新規インストールはこの状態で始まるため、mcptoon quickstart を実行するまで mcptoon の効果が実感しにくいことがあります。

この README の「99%」は、定義側の節約、つまりすべてのスキーマを読み込まないことによる節約です。CLI と serve はどちらもこれを実現しますが、direct は実現しません。結果の圧縮は別の、はるかに小さいコスト（上記のコスト2）であり、インストールする理由にはなりません。

mcptoon mode で現在のモードと、実際のカタログでの各モードのコストを確認できます。mcptoon statusline で1行のバッジを表示できます。

すべてのコマンド

mcptoon quickstart              # one-shot start (discover + configure + register the gateway)
mcptoon discover                # scan this machine for MCP servers (--write to keep, --health to probe)
mcptoon import                  # import servers from Claude Desktop / Cursor / Cline / Windsurf
mcptoon init                    # create a sample config (--auto to discover and fill it)
mcptoon list                    # show configured servers
mcptoon manifest                # all tool names (compact by default; 255 tools = 581 tokens)
mcptoon manifest --sort alpha|usage|recent       # order the list (usage = your most-called first)
mcptoon manifest --top 3 --verbose              # cap to N tools per server; --verbose adds descriptions
mcptoon inspect <server> <tool> # inspect one tool's schema
mcptoon search <query>          # search tools across servers
mcptoon select "<task>"         # top 3 tools for a task (past ~40 tools, models pick wrong)
mcptoon select "<task>" --top 5 # ...or how many you want
mcptoon call <server> <tool> '{"args":"here"}'   # call a tool
mcptoon call <server> <tool> ... --transport sse|streamable  # HTTP transport preference (default auto)
mcptoon exec python "print(len(open('big.log').readlines()))"  # run code; only stdout enters context
mcptoon exec python --file analyze.py            # same, from a script file
mcptoon exec --langs                             # what this machine can actually run
mcptoon openapi list <spec>                      # any OpenAPI/Swagger REST API as commands
mcptoon openapi call <spec> <cmd> pet-id=2       # call one operation (params: name=value)
mcptoon openapi call <spec> <cmd> --base-url U   # override the server (prod vs staging)
mcptoon openapi call <spec> <cmd> --cache-ttl 0 --cache-key v2  # re-fetch the spec; keep versions apart
mcptoon graphql list <endpoint>                  # any GraphQL endpoint as commands
mcptoon graphql call <endpoint> <cmd> --fields "name id"  # one query/mutation
mcptoon auth login <name> --auth-url U --token-url U --client-id ID  # OAuth (PKCE)
mcptoon auth creds <name> --token-url U --client-id ID  # OAuth client credentials
mcptoon auth login <name> ... --register REG_URL --client-name mine  # DCR (RFC 7591) — no client-id needed
mcptoon openapi call <spec> <cmd> --auth oauth:<name>   # use a stored token
mcptoon resources list [server]                  # list a server's MCP resources
mcptoon resources read <server> <uri>            # read one resource by URI
mcptoon prompts list [server]                    # list a server's prompt templates
mcptoon prompts get <server> <name> a=1          # render a prompt with arguments
mcptoon complete <server> <ref>:<arg>=<prefix>   # ask the server to finish a value
mcptoon bake create <name> --openapi <spec>      # save a connection under a name
mcptoon bake create <name> --openapi <spec> --auth-header 'K: env:VAR'  # secret by reference only (env:/file:)
mcptoon bake run <name> <action> ...             # reuse a saved connection
mcptoon bake install <name> --bin ~/.local/bin   # write a launcher that only carries the bake name
mcptoon add <name> --stdio|--http <cmd|url>     # add any MCP server
mcptoon remove <name>           # remove a server
mcptoon install <name> --npm|--pip|--url <pkg>  # install + auto-generate handler
mcptoon install --search <kw>   # search the live registries (nothing installed)
mcptoon update                  # refresh each server's cached tool surface; report what moved
mcptoon upgrade                 # update mcptoon itself to the latest PyPI release
mcptoon plugin install <dir>    # install an Agent Plugins 1.0.0 plugin
mcptoon sync                    # sync native config to every detected agent
mcptoon health                  # health-check every MCP server
mcptoon serve                   # run as an MCP server (stdio/HTTP)
mcptoon skills list             # list the skill catalog (--usage adds hit counts)
mcptoon skills sync <src>       # distribute a skill catalog to every agent's folder
mcptoon skills resolve "<task>" # BM25 shortlist of skills (offline, no LLM)
mcptoon docs index <dir>        # index a Markdown tree so agents stop reading it whole
mcptoon docs resolve "<query>"  # best files for a query — returns paths (offline)
mcptoon docs list               # every indexed document, by slug
mcptoon docs doctor             # check the docs index against the disk
mcptoon kb index <path>         # index documents so you can search INSIDE them
mcptoon kb fetch <url>          # fetch a URL and index it (24h TTL cache)
mcptoon kb search "<query>"     # ranked passages, not whole files (porter + trigram, RRF)
mcptoon kb list                 # indexed sources with size and age
mcptoon kb stats                # chunks, DB size, trigram support
mcptoon session                 # what happened this session (catch up after a compaction)
mcptoon bench                   # prove the savings on this machine (tools + skills, one table)
mcptoon demo                    # one command, live demo on your machine
mcptoon demo-server             # the same proof with zero downloads (11 stdlib tools)
mcptoon doctor                  # self-check: Python, config, connectivity
mcptoon status                  # one screen: what's configured, gateway wired, tokens saved
mcptoon stats                   # token-savings dashboard (vs raw JSON)
mcptoon report                  # the whole savings account: tools + skills + cumulative
mcptoon savings                 # milestones you've crossed (1B? ~12,000 novels?)
mcptoon credit                  # one screen: your mode, what it really saves, one action
mcptoon mode                    # which delivery mode you're in (cli/serve/direct) and what each costs
mcptoon statusline              # one-line savings badge for a status bar or turn header
mcptoon usage                   # local call statistics
mcptoon activity                # who used mcptoon, when, on what (last 20 calls)
mcptoon footer-facts            # one line of savings for a chat footer (never blocks)
mcptoon retrieve <handle>       # get back the original behind any --smart handle
mcptoon config                  # show gateway settings (footer, welcome, lang)
mcptoon toggle <server> <tool>  # enable/disable a single tool (--list to show all)
mcptoon policy                  # per-tool compression policy (raw / toon / slim)
mcptoon completion ps           # shell completion (bash/zsh/fish/powershell)
mcptoon off                     # remove the gateway entry from your agents (reversible)
mcptoon restore                 # drop the gateway and put your servers back
mcptoon uninstall               # full cleanup — prints the plan first (--dry to preview)

詳しいリファレンスはDEVELOPERS.mdをご覧ください。

フォーマットファミリー：4つの階層、デフォルトはコンパクト

すべて任意です。デフォルト設定がすでに最も軽量な階層です。

デフォルトが compact なのはなぜですか？ どのツールを使うかを選ぶのに必要なのは名前だけです（255個のツールで581トークン）。パラメーターの詳細は呼び出し時に必要となり、オンデマンドで取得できます。デフォルトで完全なスキーマを読み込むと、節約できるはずの99.2%がそのまま失われます。

エージェント向けのルール：選択には manifest、呼び出す前には inspect を使います。 実際に使用されている41個のツールで測定したところ、名前だけから引数を推測するエージェントの有効な呼び出しは約10%にとどまります。一方、1ターンで実際に使う2〜3個のツールに対して一度 inspect を実行するエージェントは、すべてのスキーマを注入した場合と同じ100%に達し、コストはごくわずかです。

信頼と安全性

わずか534KBのネイティブCLIです。いつでも削除でき、そのまま使い続ければ、どのエージェントでもツールやスキルを設定する必要がなくなります。 mcptoonはエージェントの設定に触れるため、透明性を重視して設計されており、いつでも簡単に利用をやめられます。

エージェントに渡される前に、すべてのツールの結果に対して次の3つのガードが実行されます。

• 元に戻せます。 mcptoon restore は乗っ取りを元に戻し（ゲートウェイを削除してサーバーを元に戻します）、mcptoon off はゲートウェイのエントリーだけを削除します。mcptoon uninstall --dry は、削除計画全体を事前に表示します。要求しない限り、サーバーが削除されることはありません。
• テレメトリーはありません。 分析情報も、クラッシュレポートも、外部への送信も一切ありません。
• ローカル優先です。 ツール、スキル、ファイルはお使いのマシンに保存されます。外部に送信されるのは install --search のリクエストだけで、レジストリからカタログ一覧を取得します。データが送信されることはありません。
• 認証情報は保存しません。 APIキーは設定または環境変数から直接渡されます。
• 依存関係はありません。 Python標準ライブラリのみを使用しているため、監査が必要なサプライチェーンはありません。 CIでは scripts/check_zero_deps.py によってこれを徹底しています。
• デーモンはありません。 純粋なCLIのため、常駐プロセスもリスニングポートもありません。
• フォーマットによって互換性が損なわれることはありません。 ワイヤープロトコルは常に標準のJSON-RPCです。compact/slim/toonは、mcptoonからエージェントへの出力にのみ影響します。--toon のデコードに失敗した場合はJSONにフォールバックし、--full を1つ指定すればネイティブスキーマに戻ります。ロックインはありません。

対象範囲を一言で言うと： mcptoonはインデックス兼設定マネージャーです。各ツールのソースを案内するだけで、ソース自体はそれぞれ独自の条件に沿って確認できます。

クレジットと参考資料

• TOON standard — v4.1（MIT）。python-toonからベンダリングされ、NOTICEにクレジットを記載
• ToonDeck — mcptoon向けGUIコンソール （プレアルファ版）：同じエンジンを使用し、コマンドを入力する代わりにポイント＆クリックで操作できます

開発者： mcptoonは@activeing123が保守する独立したサードパーティープロジェクトです。Anthropicとは関係ありません。

コントリビュート

git clone https://github.com/activeing123/mcptoon.git
cd mcptoon
pip install -e . --no-build-isolation
pip install pytest pytest-cov
python -m pytest tests/ -v   # 3013 passed, 2 skipped

守るべきルールは3つです。依存関係ゼロ（CIで徹底）、新しい動作にはテストを追加、Windowsを第一級の対象とすることです。初めての方は、CONTRIBUTING.mdと DEVELOPERS.mdから始めてください。

コードベース：56個のモジュールにわたるPython 41,144行、サードパーティー依存関係ゼロ。

サポート

エラーが発生しましたか？トラブルシューティングとFAQでは、よくある問題を取り上げています （Server 'X' not configured、skills syncの誤削除防止ゲート、未知のコマンド／オプションの終了コード、保存時の進捗が100%ではなく99%と表示される理由、古いスキル数など）。

mcptoonは個人が運営するサイドプロジェクトで、個人利用は引き続き無料です。コンテキスト料金を節約できた場合は、ぜひご支援ください。

• GitHubでスポンサーになる — 単発または月額で支援できます。
• リポジトリにスターを付ける — ほかの開発者が小さなツールを見つけるきっかけになります。

チーム向け機能はまだ開発されていません。 全チームメンバーのマシンに同期される共通サーバーリストや、いつ何が読み込まれたかのログなどを予定しています。料金もウェイトリストページもありません。[email protected]にメールをいただければ、優先度を上げます。

ライセンス

Apache 2.0。詳細はLICENSEと NOTICEをご覧ください。