Gemini MCPを使っているユーザーなら、一度は遭遇する可能性があるのが「$defs参照が含まれているJSONスキーマでのエラー」。Gemini APIは、これらのスキーマを受け入れず、400エラーが発生してしまうことがあります。この問題、実は業界でも注目されており、いくつかのMCPサーバーでは重要なツールが使えなくなるという影響も出ています。この記事では、Gemini MCPを使いこなすために、エラーを解決する方法をステップごとに解説し、さらに今後この問題を回避するための実践的な対策を提案します。
Gemini MCPで発生する$defs参照エラーとは？
AIのイメージ
Gemini MCPは多くの開発者や企業で利用されていますが、特にMCPサーバー（Snowflake MCP、BEADS MCP、Basic Memory MCPなど）において、JSONスキーマに含まれる$defs参照が原因でAPIエラーが発生します。このエラーは、Gemini CLIを使用してMCPサーバーと通信した際に、以下のような問題を引き起こします。
- APIが400エラーを返し、ツール呼び出しが拒否される。
- MCPサーバーは接続状態を維持しているものの、ツール呼び出しが失敗する。
- スキーマに$defs参照が含まれていると、Gemini APIがこれを受け入れない。
この問題の本質は、$defsがMCPツールのスキーマで重要な役割を果たしていることにあります。多くのMCPサーバーで使用される$defsは、スキーマの再利用や複雑なデータ構造を効率的に扱うために重要です。しかし、Gemini APIがこれを処理できないため、エラーが発生します。
エラーを解決するためのステップとツールの活用法
実は、この問題に対する解決策は複数あります。以下に、最も効果的な解決方法をいくつか紹介します。
MCPサーバーをFastMCP 2.12以上にアップデートする
FastMCPは、Gemini APIとの互換性問題を解決するためにアップデートされています。特にFastMCP 2.12以降では、$defs参照を正しく処理できるように修正されています。これにより、多くのMCPツールが正常に動作するようになります。
process_schemaを使ってスキーマを変換する
Googleの内部ツール「process_schema」を使って、MCPツールスキーマをGemini APIと互換性のある形式に変換する方法があります。これにより、$defsを取り除き、API側でエラーを防ぐことができます。この方法を使用することで、スキーマの問題を手動で解決せずに済みます。
スキーマフラット化を試みる
スキーマフラット化は、$defs参照を取り除く方法の一つです。これを手動で実装するか、既存のフレームワークを使うことで、エラーを回避できます。例えば、FastMCPが提供するフラット化パターンを参考にすることで、$defs参照を削除してMCPツールを正常に動作させることができます。
Gemini MCPに関する疑問解決
Gemini MCPで$defs参照エラーを解決するために最初に行うべきことは何ですか？
まず、エラーが発生しているMCPサーバーを確認し、そのバージョンがFastMCP 2.12以上であるかをチェックしましょう。もし古いバージョンを使用している場合は、最新のバージョンにアップデートすることで、問題が解決する可能性が高いです。
スキーマのフラット化を手動で行う方法はありますか？
はい、スキーマをフラット化することで、$defsを取り除くことができます。Googleが提供しているprocess_schemaツールを使うと、自動的にスキーマを変換できますが、手動で行う場合は、$defsの参照をすべて削除し、スキーマを簡素化する作業が必要です。
【警告】このままでは、AI時代に取り残されます。
あなたの市場価値は一瞬で陳腐化する危機に瀕しています。
今、あなたがGeminiの表面的な使い方に満足している間に、ライバルたちはAIを「戦略的武器」に変え、圧倒的な差をつけています。数年後、あなたの仕事やキャリアは、AIを本質的に理解している人材によって「奪われる側」になっていませんか？
未来への漠然とした不安を、確かな自信と市場価値に変える時です。
当サイトでは、ChatGPTをはじめとする生成AIの「なぜそう動くのか」という原理と、「どう活用すれば勝てるのか」という全体戦略を徹底的に解説している記事を多く掲載しています。
単なる操作方法ではなく、AIを指揮するリーダーになるための思考と知識を、網羅的に提供します。
取り残される恐怖を、未来を掴む確固たる自信に変えるための戦略図。あなたのキャリアを成功に導く決定的な一歩を、当サイトの記事を読んで踏み出してください！ 読んだ瞬間から、あなたはAIの波に乗る側になります。
他の記事は下記のリンクからご覧いただけます。
NanoBanana（Gemini 2.5 Flash Image）の記事一覧はこちら
まとめ
Gemini MCPを活用するためには、$defs参照によるAPIエラーを解決することが不可欠です。この問題は、多くのMCPサーバーに影響を与えていますが、FastMCPのアップデートやスキーマのフラット化を行うことで、エラーを回避することが可能です。特にFastMCP 2.12以上を利用することで、迅速に問題を解決できるため、アップデートを検討することを強くお勧めします。
コメント