Claude Media
ListMcpResourcesToolとReadMcpResourceToolでMCPのresourcesを読む
Claude CodeMCPTips

ListMcpResourcesToolとReadMcpResourceToolでMCPのresourcesを読む

Claude Codeが持つMCP resources用の2ツールの役割、権限確認が不要な点、@メンションとの使い分け、UI resourcesの扱いの違いを示します。

読了目安 約11分

ListMcpResourcesTool は接続済みMCPサーバーのresource一覧を取るツールで、ReadMcpResourceTool はURIを指定して中身を読むツールです。どちらもClaude Codeの組み込みツールで、権限の確認は求められません。人間が使う入口は @ メンションで、2つのツールはClaudeが自分で探しに行く経路にあたります。

2つのツールは何をするのか

Claude Codeのツール一覧には、MCP resources向けに次の2行があります。

ツール役割権限確認
ListMcpResourcesTool役割接続済みMCPサーバーが公開するresourcesを一覧する権限確認不要
ReadMcpResourceTool役割URIを指定して特定のMCP resourceを読む権限確認不要

一覧ツールは、MCP AppsのUI resourcesを結果から外します。UI resourcesは、ホストアプリケーションが描画するためのページだからです。

役割分担は単純です。まず一覧で「何が読めるか」を知り、次にURIを渡して中身を取ります。

MCPの仕様側でいう resources/list と resources/read に、それぞれ対応する操作と考えると整理しやすくなります。仕様そのものの読み方はMCPのResources仕様を読み解くにまとめています。この記事はClaude Code側、つまりクライアントがどう扱うかに絞ります。

2つのツールの入力パラメータ名は、ツール一覧のページに記載がありません。パラメータを推測して設定に書くのは避けたほうがよく、呼び出しはClaudeに任せるのが確実です。

誰がいつ呼ぶのか

MCPのドキュメントには「サーバーが対応していれば、Claude Codeがresourcesの一覧・読み取り用のツールを自動で提供する」とあります。つまり、MCPサーバーを足しただけで、追加の設定なしに2つのツールが使える状態になります。

呼び出しの場面は2通りです。

  • 自分で @ を打たず、「接続しているMCPサーバーにどんな資料がある?」と聞く。Claudeが一覧ツールを呼びます
  • 一覧で見つけたURIについて、「その内容を読んで要約して」と頼む。Claudeが読み取りツールを呼びます

たとえば次のような依頼です。

接続中のMCPサーバーが公開しているresourcesを一覧にして。
その中から、データベースのスキーマに当たるものを読んで要点を教えて。

この依頼で実際にどのツールがどの順で呼ばれるかは、サーバーの実装と会話の文脈で変わります。どのツールが呼ばれたかは、セッション上のツール呼び出し表示で確認できます。

@メンションとの使い分け

同じresourcesは、@server:protocol://resource/path の形でプロンプトに直接書いて参照することもできます。

@github:issue://123 を分析して、修正案を出して

参照したresourceは、添付として自動的に取得されます。入力中に @ を打つと、接続中の全サーバーのresourcesがファイルと並んで候補に出て、パスはあいまい検索もできます。

両者の違いを表にまとめます。

観点@メンション2つのツール
誰が起点か@メンション自分(URIを知っている)2つのツールClaude(探索から任せる)
URIの事前把握@メンション必要(候補メニューで補える)2つのツール不要(一覧から見つける)
取得のされ方@メンション添付として自動で取り込まれる2つのツールClaudeがツールとして呼ぶ
向く場面@メンション対象が決まっている2つのツール何があるか分からない

対象のURIが決まっているなら @ が手早く、確実にプロンプトへ載ります。探索から任せたい、複数サーバーを横断して探したい、というときはツール経由が合います。両方を併用しても問題ありません。

UI resourcesが見えないときの読み方

一覧に何も出ないときは、サーバーがresourcesを持たないのではなく、UI resourcesしか持たない可能性があります。

UI resourcesとは、URIが ui:// で始まるか、メディアタイプが text/html;profile=mcp-app のエントリです。Claudeが読む内容ではなく、ホストが表示するためのページなので、次の場所には出てきません。

  • @ の候補
  • ListMcpResourcesTool の結果

UI resourcesしか持たないサーバーでは、resourceの一覧が空に見えます。ただし、URIを直接指定すれば ReadMcpResourceTool で読み取れます。

一覧が空のときの切り分けは、次の順が手早いです。

  1. /mcp でサーバーが接続済みか確かめる
  2. サーバーがresourcesを公開しているか、サーバー側のドキュメントで確かめる
  3. 公開しているのに空なら、UI resourcesだけを返している可能性を疑う

接続が失敗しているなら/mcp reconnect allで一括再接続する方法が使えます。

サーバー側の更新はどう反映されるか

Claude CodeはMCPの list_changed 通知に対応しています。サーバーがtools、prompts、resourcesの構成を変えて通知を送ると、切断・再接続なしで一覧が更新されます。

更新の取得に失敗しても、直前に取得済みのresourcesは残ります。v2.1.214より前のバージョンでは、一時的なエラーで一覧が空になっていました。

接続直後には、tools/list、prompts/list、resources/list などの探索リクエストが送られます。一時的なネットワークエラーやサーバーエラーのときは最大3回まで短い待機を挟んで再試行し、認証エラー、4xx応答、タイムアウトは再試行しません。

resourceが古いままのときは、/mcp から該当サーバーを再接続すると手早く更新できます。

大きなresourceを読むときの出力上限

resourceの中身が大きいと、読み取り結果がコンテキストを圧迫します。MCPのドキュメントには、MCPツールの出力に対する上限が次のように書かれています。

  • 出力が10,000トークンを超えると警告が出る(この閾値は固定)
  • 既定の上限は25,000トークンで、MAX_MCP_OUTPUT_TOKENS 環境変数で変えられる
  • 画像を含まない結果が上限を超えると、内容はファイルに保存され、会話にはそのファイルパスを示すメッセージが入る。保存先はセッションの tool-results ディレクトリ(~/.claude/projects/ 配下)で、Claudeは必要になったときにそのファイルを読む

上限を上げる場合は、起動前に環境変数を設定します。

export MAX_MCP_OUTPUT_TOKENS=50000
claude

サーバーの作り手側には、tool単位で上限を引き上げる _meta["anthropic/maxResultSizeChars"] という注釈があります。上限の天井は500,000文字で、この注釈があるtext出力には MAX_MCP_OUTPUT_TOKENS が効きません。

この注釈は、データベースのスキーマや完全なファイルツリーのように、大きくても必要な出力を返すtool向けです。自分で管理していないサーバーで警告が頻発するなら、MAX_MCP_OUTPUT_TOKENS を上げるか、サーバーの作り手に注釈の追加や応答のページ分割を頼む、という手があります。画像を返すtoolには注釈が効かないため、上げられるのは環境変数だけです。

ただし、この節の記述は「MCP tool output」を対象にしています。ReadMcpResourceTool の結果に同じ上限が同じ形で掛かるかは、ドキュメントに明記がありません。resourceが極端に大きいサーバーでは、実際に読ませて警告やファイル保存の挙動を確かめてください。

権限とCLAUDE.mdで制御する

2つのツールは権限確認が「不要」です。この前提で、運用に効く設定が2つあります。

使わせたくないときはdenyで外す

resourcesの中身を読ませたくないなら、権限ルールのdenyにツール名をそのまま書きます。この2つのツールは括弧付きの指定子を取らず、ツール名だけが書式になります。ツール名だけでdenyしたツールはClaudeのコンテキストから取り除かれます。

{
  "permissions": {
    "deny": ["ListMcpResourcesTool", "ReadMcpResourceTool"]
  }
}

MCPのtoolsを止めたい場合は、mcp__<server>__<tool> の形式が別に必要です。書き方はMCP権限ルールのserver:tool単位の書き方で扱っています。resources側は、この2つのツール名を指定して止めます。

denyにはツール名のglobも書けます。"mcp__*" は全サーバーのMCP toolに一致し、ツール名だけのglobでdenyしたツールは、ツール名そのままのdenyと同じくClaudeのコンテキストから取り除かれます。ただし2つのツールの名前は mcp__ で始まらないため、mcp__* のdenyには一致しません。MCP toolを丸ごと止めたつもりでも、resourcesの2ツールは残ります。両方止めたいときは、"mcp__*" と2つのツール名を並べて書きます。

{
  "permissions": {
    "deny": ["mcp__*", "ListMcpResourcesTool", "ReadMcpResourceTool"]
  }
}

denyに書いたツール名が既知のツールのどれにも一致しないと、起動時に警告が出ます。打ち間違いを見つけるための仕組みです。ただし名前に _ や * を含むものは検査の対象外で、2つのツール名には _ がないため、綴りを誤れば警告で気づけます。

CLAUDE.mdで探索の順序を決める

Claudeにresourcesの使い方を任せるなら、CLAUDE.mdに探索の順序を書いておくと動作がそろいます。例として、次のような書き方が考えられます。

## MCP resourcesの扱い
- 接続中のMCPサーバーの資料を探すときは、まずListMcpResourcesToolで一覧を取る
- 読むのは、依頼に関係するURIだけにする
- 読んだURIは、回答の末尾に列挙する

「読んだURIを列挙する」の一行を入れておくと、どのresourceに基づいた回答かをあとから追えます。

動作の確認は実際に聞いて行う

設定したあとは、実際に頼んで挙動を見ます。

MCPのresourcesを一覧にして。その後、先頭のものを読んで内容を要約して。

ツール呼び出しの表示に2つのツール名が出ていれば、経路は動いています。denyに入れたなら、逆にツール自体が使えない旨の応答になることを確かめます。

MCPサーバー側のtoolの正確な名前は、/mcp で確認できます。組み込みの2ツールの名前は、この記事の表のとおりです。

落とし穴と切り分け

resources周りでつまずきやすい点を、症状別に並べます。

症状考えられる原因確認方法
一覧が空考えられる原因サーバーがUI resourcesしか持たない / 未接続確認方法/mcp で状態を確認
@ の候補に出ない考えられる原因同上(UI resourcesは候補に出ない)確認方法URIを直接指定して読む
resourceが更新されない考えられる原因list_changed 通知が届いていない確認方法/mcp から再接続
読ませたくない考えられる原因権限確認が不要なため止まらない確認方法denyにツール名を書く

MCPサーバーを増やすと、tools側の定義がコンテキストを圧迫する問題が別にあります。toolsの定義が増えたときの対策はMCPのトークンオーバーヘッドを抑える設定を参照してください。

まとめ

ListMcpResourcesTool と ReadMcpResourceTool は、サーバーを繋ぐだけで使える、resources専用の探索と読み取りの組です。権限確認が要らない点が最大の特徴で、読ませない運用にしたいときはdenyへ名前を書きます。

対象が決まっているなら @server:protocol://path、何があるか分からないならClaudeに一覧を任せる、という使い分けが基本線です。一覧が空でも、UI resourcesしか持たないだけかもしれないので、まず /mcp で接続を見てからURI指定の読み取りを試すと切り分けが早く済みます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →