ListMcpResourcesToolとReadMcpResourceToolでMCPのresourcesを読む

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

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

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

まず一覧で「何が読めるか」を知り、次にURIを渡して中身を取る。役割分担はこれだけです。MCPの仕様でいう resources/list と resources/read が、それぞれの相手にあたります。仕様そのものはMCPのResources仕様を読み解くで扱っているので、ここではクライアントであるClaude Code側の振る舞いを追います。

サーバーがresourcesに対応していれば、ツールはClaude Code側が自動で用意します。MCPサーバーを足した時点で使える状態になり、追加の設定は要りません。

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

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

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

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

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

@メンションかツールか、起点で選ぶ

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

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

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

両方を併用しても問題ありません。対象が決まっている依頼は @ で、決まっていない依頼はツールで、と起点で選べば足ります。

一覧が空のときの切り分け

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

UI resourcesは、URIが ui:// で始まるか、メディアタイプが text/html;profile=mcp-app のエントリです。Claudeが読む内容ではなく、ホストアプリケーションが描画するためのページなので、@ の候補にも ListMcpResourcesTool の結果にも出ません。UI resourcesしか持たないサーバーでは、一覧が空に見えます。URIを直接指定すれば、ReadMcpResourceTool で読み取れます。

サブエージェントで届かない・「対応していない」と返る

resourcesの2ツールは、呼べる場面が限られることがあります。公式ドキュメントとGitHubのissueから、症状別に並べます。

バックグラウンドのサブエージェントは2ツールを持たない

サブエージェントはバックグラウンドで動くのが既定です。サブエージェントのドキュメントによると、バックグラウンドのサブエージェントは、MCPのツールはすべて引き継ぎますが、組み込みツールは決まった許可リストの分だけ残ります。リストには Read、Bash、WebFetch などが並びますが、ListMcpResourcesTool と ReadMcpResourceTool は入っていません。

それ以外の組み込みツールは、継承したものも tools フィールドに書いたものも取り除かれ、エラーは出ません。同じサブエージェント定義でも、フォアグラウンドで動かすと2ツールが使え、バックグラウンドでは使えない、という差が生まれます。会話のフォーク(fork)は、親会話のツールをそのまま受け取るので影響を受けません。

この挙動はGitHubのissue #85230でも報告されています。v2.1.226で、サブエージェントが長時間MCPサーバーのtoolsを使い続けたのに、サーバーが配るドキュメントのresourcesには届かなかった、という内容です。報告者が挙げた回避策は、フォアグラウンドで動かす、フォークを使う、親でresourceを読んで内容をプロンプトに貼る、の3つでした。

サーバーがresourcesを公開しているのに「対応していない」と返る

もう1つは、resourcesを公開しているのに、Claude Code側が持っていないものとして扱うケースです。次は、報告されたメッセージの実例です。

#92729の報告者は、Streamable HTTPの自作サーバーが initialize の応答で resources の機能を宣言していて、resources/list も resources/read も正常に返るのに、上の2つが出たと書いています。同じセッションにある別のstdioサーバーのresourcesは、問題なく一覧に出ていました。サーバーの実装ではなく、クライアント側の扱いを疑う材料になります。

#80300は、macOSのstdioサーバーで、Claude Codeを再起動した後に読み取りツールが使えなくなった報告です。このメッセージは、読み取り先の問題ではなく、ツールがその文脈で有効になっていない状態を示しています。

同じ症状に当たったら、サーバー側のログと /mcp の接続状態を見て、サーバーの問題とクライアントの問題を先に分けます。

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

Claude CodeはMCPの list_changed 通知に対応しています。サーバーがtools、prompts、resourcesの構成を変えて通知を送ると、インタラクティブなセッションでは、切断・再接続なしで一覧が更新されます。

-p フラグの非対話モードとAgent SDKでは、通知を受けて更新されるのはツール一覧だけです。resourcesやpromptsの一覧が、この通知で更新されるとは書かれていません。

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

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

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

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

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

画像を含まない結果が上限を超えると、内容はファイルに保存され、会話にはそのファイルのパスを示すメッセージが入ります。保存先はセッションの tool-results ディレクトリ(~/.claude/projects/ 配下)で、Claudeは必要になったときにそのファイルを読みます。

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

export MAX_MCP_OUTPUT_TOKENS=50000
claude

サーバーの作り手側には、toolの定義(tools/list の応答)に _meta["anthropic/maxResultSizeChars"] という注釈を付ける方法があります。注釈のあるtoolのtext出力には、MAX_MCP_OUTPUT_TOKENS が効きません。データベースのスキーマや完全なファイルツリーのように、大きくても必要な出力を返すtool向けです。

自分で管理していないサーバーで警告が頻発するなら、MAX_MCP_OUTPUT_TOKENS を上げるか、サーバーの作り手に注釈の追加や応答のページ分割を頼む手があります。画像を返すtoolには注釈が効かないので、上げられるのは環境変数だけです。

これらの記述が対象にしているのは「MCP tool output」です。resourceを読ませる前に、小さいURIで試して警告やファイル保存の挙動を見ておくと、極端に大きなresourceで会話が埋まるのを避けられます。

権限とCLAUDE.mdで制御する

2つのツールは権限確認が「不要」なので、止めたいときは自分でdenyに書くことになります。

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

resourcesの中身を読ませたくないなら、権限ルールのdenyにツール名をそのまま書きます。ツール名だけでdenyしたツールは、Claudeのコンテキストから取り除かれます。

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

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

denyにはツール名のglobも書けます。"mcp__*" は全サーバーのMCP toolに一致しますが、2つのツールの名前は mcp__ で始まらないので、このdenyには一致しません。MCP toolを丸ごと止めたつもりでも、resourcesの2ツールは残ります。両方止めたいときは、次のように並べます。

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

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

設定ファイルを触らず、そのセッションだけ止めるなら、起動時のフラグでも指定できます。v2.1.289の claude --help には、次の行があります。

claude --help | grep -A2 -- "--disallowedTools"

  --disallowedTools, --disallowed-tools <tools...>
      Comma or space-separated list of tool names to deny (e.g. "Bash(git *)
      Edit")

例の "Bash(git *) Edit" と同じ書き方で、ListMcpResourcesTool ReadMcpResourceTool のようにツール名を並べます。ヘルプには --tools もあり、使えるツールを組み込みの集合から名前で絞り込めます。

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

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

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

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

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

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

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

ツール呼び出しの表示に2つのツール名が出ていれば、経路は動いています。denyに入れたなら、逆にツール自体が使えない旨の応答になることを確かめます。MCPサーバー側のtoolの正確な名前は、/mcp で確認できます。

MCPサーバーを増やすと、tools側の定義がコンテキストを圧迫する問題も出てきます。toolsの定義が増えたときの対策はMCPのトークンオーバーヘッドを抑える設定にまとめています。

まとめ

2つのツールは、サーバーを繋ぐだけで使える探索と読み取りの組で、権限確認がない分、止めたいときはdenyにツール名を書く必要があります。一覧が空でも、まず /mcp で接続を見て、UI resourcesだけの可能性を考えてからURI指定の読み取りを試すと早く切り分けられます。サブエージェントに読ませたい場合は、バックグラウンドでは2ツールが使えないことを前提に、フォアグラウンドで動かすか、親で読んでから渡します。既定の対話セッションではClaudeがフォアグラウンドを指定できないため、前者は環境変数 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 でバックグラウンド実行を無効にする形になります。