MCP ツールの使い方

MCP サーバーを追加して接続すると、そのサーバーが提供するツールは自動的に Agent の利用可能なツールセットに登録されます。このページでは、ツールがどのように検出・命名・使用されるか、および詳細な管理方法について説明します。

ツールの自動検出

MCP サーバーが正常に接続されると、Elftia は以下の処理を自動的に行います：

1. ツールリストの取得 — サーバーの listTools エンドポイントを呼び出して、利用可能なすべてのツールを取得します
2. フォーマットの登録 — ツールを内部ツールシステムに登録します
3. キャッシュ保存 — 頻繁なリクエストを避けるため、ツールリストを 5 分間キャッシュします

キャッシュの動作

動作	説明
キャッシュ期間	5 分（300 秒）
キャッシュ範囲	サーバー ID ごとに個別にキャッシュ
自動更新	キャッシュ期限切れ後、次のリクエスト時に最新のリストを自動取得
手動更新	MCP サーバーリストの Discover ボタンをクリックして強制更新
再接続	サーバーを切断して再接続すると、そのサーバーのキャッシュがクリアされます

手動検出

MCP サーバーページで、各サーバーに対して Discover を実行すると、そのサーバーが提供する機能の完全なサマリーを確認できます：

• ツール（Tools） — Agent が呼び出せる機能
• リソース（Resources） — サーバーが提供するデータリソース（ファイル、データベーステーブルなど）
• プロンプト（Prompts） — サーバーがあらかじめ定義したプロンプトテンプレート

ツールの命名フォーマット

Agent 内での各 MCP ツールの識別子は以下のフォーマットに従います：

mcp__<server-name>__<tool-name>

命名規則：

• サーバー名とツール名の英数字以外の文字はアンダースコア _ に置換されます
• セパレーターとしてダブルアンダースコア __ が使用されます

例：

サーバー名	元のツール名	Agent 内の識別子
filesystem	read_file	mcp__filesystem__read_file
brave-search	brave_web_search	mcp__brave_search__brave_web_search
github	create_issue	mcp__github__create_issue

MCP の使用モード

Elftia は 3 つの MCP 使用モードを提供しており、会話中のツールの利用可否を制御します：

モード	説明	ユースケース
自動（デフォルト）	有効なすべてのサーバーのツールが自動的に利用可能	日常使用；Agent が自分でツールを選択する
手動	会話ごとに使用するサーバーを選択	ツールのスコープを正確に制御する必要があるシナリオ
無効	MCP ツールを完全にオフにする	外部ツールを必要としないシンプルな会話

自動モード

デフォルトモードです。アクティブ（isActive）なすべての MCP サーバーのツールが、Agent のツールリストに自動的に追加されます。Agent は会話内容に基づいて、ツールを呼び出すかどうかを自分で判断します。

手動モード

手動モードでは、現在の会話で使用する MCP サーバーを正確に選択できます：

1. 会話設定で MCP モードを 手動 に切り替えます
2. 利用可能なサーバーリストから必要なサーバーにチェックを入れます
3. 選択したサーバーのツールのみが会話中に利用可能になります

無効モード

MCP 機能を完全に無効にします。Agent はいかなる MCP ツールも読み込みません。

ツールフォーマットの適応

Elftia は複数の LLM プロバイダーをサポートしており、それぞれ異なるツール呼び出しフォーマットを持っています。MCP ツールは現在のプロバイダーが要求するフォーマットに自動変換されます：

プロバイダー	ツールフォーマット	説明
OpenAI / DeepSeek / 中国系 LLM	function フォーマット	{ type: "function", function: { name, description, parameters } }
Anthropic (Claude)	tool フォーマット	{ name, description, input_schema }
Google (Gemini)	functionDeclarations フォーマット	{ functionDeclarations: [{ name, description, parameters }] }

この変換は完全に自動で行われ、手動での操作は必要ありません。

会話でのツールの表示

Agent が MCP ツールを呼び出すと、会話 UI に専用のツール呼び出しカードが表示されます：

• 呼び出し中 — ツール名と渡された引数を表示
• 結果 — ツールが返したコンテンツを表示（テキスト、画像など）
• エラー — 呼び出しに失敗した場合、エラーの詳細を表示

ツールが返すコンテンツの種類

MCP ツールは以下の種類のコンテンツを返すことができます：

コンテンツの種類	説明
text	テキスト結果、そのまま表示
image	画像データ（Base64 エンコード）、画像としてレンダリング
audio	音声データ（Base64 エンコード）、プレーヤーとしてレンダリング

呼び出しタイムアウト

単一のツール呼び出しのタイムアウトは 2 分（120 秒）です。ツールがこの時間内に結果を返さない場合、呼び出しは終了してタイムアウトエラーが返されます。

MCP サーバーと Agent の関連付け

特定の MCP サーバーを特定の Agent に関連付けることで、ツールの割り当てをより細かく制御できます：

関連付けの手順

1. MCP サーバーリストで、対象サーバーの 管理ボタンをクリックします
2. 表示されたダイアログで、すでに関連付けられている Agent のリストを確認します
3. Agent に追加をクリックして、利用可能な Agent のリストを展開します
4. 関連付けたい Agent を選択します

関連付けの管理

管理ダイアログでは以下の操作が可能です：

操作	説明
関連付け済み Agent の確認	現在どの Agent が関連付けられているかを表示
有効化/無効化	トグルを使って特定の Agent に対するツールの利用可否を制御
関連付けの解除	削除ボタンをクリックして Agent の関連付けを解除
Agent の検索	追加時に Agent リストを検索・フィルタリング

特定ツールの無効化

MCP サーバーが提供するツールが多すぎる場合、または Agent に使わせたくない特定のツールがある場合、選択的に無効化できます：

• サーバーレベルの disabledTools リストに無効化されたツールの名前が記録されます
• 無効化されたツールは Agent のツールリストに表示されません
• 無効化はサーバー更新インターフェースを通じて行います

信頼管理

MCP サーバーには 2 つの信頼レベルがあります：

レベル	説明	動作の違い
未信頼（デフォルト）	新しく追加されたサーバーはデフォルトで未信頼	通常使用だが、追加の制限がかかる場合あり
信頼済み	ユーザーが明示的に信頼できるとマークしたサーバー	ツール呼び出しを完全に信頼

信頼済みとしてマーク

サーバー管理でサーバーの isTrusted プロパティを更新すると、信頼済みとしてマークできます。信頼済みサーバーは、ツール呼び出しが自動承認される際に高い権限が与えられます。

サーバーの有効化と無効化

各 MCP サーバーには isActive トグルがあります：

• 有効 — サーバーがツールの読み込みに参加します（自動モードでは自動接続されます）
• 無効 — サーバーはスキップされ、ツールの読み込みに参加せず、接続リソースも消費しません

サーバーを無効にしても設定は削除されず、いつでも再度有効化できます。

トラブルシューティング

ツール呼び出しがエラーを返す

症状：Agent がツールを呼び出した後にエラーメッセージが表示される。

解決策：

• ツールに必要な API キーが正しく設定されているか確認する
• ツールの引数が期待されるフォーマットと一致しているか確認する
• サーバーがまだ動作しているか確認する（Stdio サーバーの場合）
• サーバーの再接続を試みる

ツールリストが空

症状：サーバーは接続されているがツールが検出されない。

解決策：

• Discover 機能を使ってツールリストを手動取得する
• サーバーのバージョンが tools/list エンドポイントをサポートしているか確認する
• サーバーのログ出力にエラーがないか確認する

Agent が利用可能なツールを使用しない

症状：ツールは登録されているが、会話中に Agent がツールを呼び出さない。

解決策：

• プロンプトでツール名や関連する機能を明示的に言及する
• モードが無効に設定されていないか確認する
• ツールの説明が正確で、Agent がいつ使用すべきかを判断できるか確認する
• 利用可能なツールの数を減らして、選択の麻痺を避ける

次のステップ

• MCP サーバーの追加 — 追加の MCP サーバーを設定する
• JSON 一括インポート — JSON を使って設定をすばやくインポートする
• MCP 概要 — MCP のコアコンセプトを確認する