feat(core): add tools to list and read MCP resources

docs/cli/plan-mode.md

@@ -130,7 +130,9 @@ These are the only allowed tools:
   [`cli_help`](../core/subagents.md#cli-help-agent)
 - **Interaction:** [`ask_user`](../tools/ask-user.md)
 - **MCP tools (Read):** Read-only [MCP tools](../tools/mcp-server.md) (for
-  example, `github_read_issue`, `postgres_read_schema`) are allowed.
+  example, `github_read_issue`, `postgres_read_schema`) and core
+  [MCP resource tools](../tools/mcp-resources.md) (`list_mcp_resources`,
+  `read_mcp_resource`) are allowed.
 - **Planning (Write):**
   [`write_file`](../tools/file-system.md#3-write_file-writefile) and
   [`replace`](../tools/file-system.md#6-replace-edit) only allowed for `.md`

docs/reference/tools.md

@@ -92,6 +92,13 @@ each tool.
 | [`ask_user`](../tools/ask-user.md) | `Communicate` | Requests clarification or missing information via an interactive dialog.               |
 | [`write_todos`](../tools/todos.md) | `Other`       | Maintains an internal list of subtasks. The model uses this to track its own progress. |
 
+### MCP
+
+| Tool                                              | Kind     | Description                                                            |
+| :------------------------------------------------ | :------- | :--------------------------------------------------------------------- |
+| [`list_mcp_resources`](../tools/mcp-resources.md) | `Search` | Lists all available resources exposed by connected MCP servers.        |
+| [`read_mcp_resource`](../tools/mcp-resources.md)  | `Read`   | Reads the content of a specific Model Context Protocol (MCP) resource. |
+
 ### Memory
 
 | Tool                                             | Kind    | Description                                                                          |

docs/sidebar.json

@@ -122,7 +122,14 @@
               }
             ]
           },
-          { "label": "MCP servers", "slug": "docs/tools/mcp-server" },
+          {
+            "label": "MCP servers",
+            "collapsed": true,
+            "items": [
+              { "label": "Overview", "slug": "docs/tools/mcp-server" },
+              { "label": "Resource tools", "slug": "docs/tools/mcp-resources" }
+            ]
+          },
           { "label": "Model routing", "slug": "docs/cli/model-routing" },
           { "label": "Model selection", "slug": "docs/cli/model" },
           {

docs/tools/mcp-resources.md

@@ -0,0 +1,44 @@
+# MCP resource tools
+
+MCP resource tools let Gemini CLI discover and retrieve data from contextual
+resources exposed by Model Context Protocol (MCP) servers.
+
+## 1. `list_mcp_resources` (ListMcpResources)
+
+`list_mcp_resources` retrieves a list of all available resources from connected
+MCP servers. This is primarily a discovery tool that helps the model understand
+what external data sources are available for reference.
+
+- **Tool name:** `list_mcp_resources`
+- **Display name:** List MCP Resources
+- **Kind:** `Search`
+- **File:** `list-mcp-resources.ts`
+- **Parameters:**
+  - `serverName` (string, optional): An optional filter to list resources from a
+    specific server.
+- **Behavior:**
+  - Iterates through all connected MCP servers.
+  - Fetches the list of resources each server exposes.
+  - Formats the results into a plain-text list of URIs and descriptions.
+- **Output (`llmContent`):** A formatted list of available resources, including
+  their URI, server name, and optional description.
+- **Confirmation:** No. This is a read-only discovery tool.
+
+## 2. `read_mcp_resource` (ReadMcpResource)
+
+`read_mcp_resource` retrieves the content of a specific resource identified by
+its URI.
+
+- **Tool name:** `read_mcp_resource`
+- **Display name:** Read MCP Resource
+- **Kind:** `Read`
+- **File:** `read-mcp-resource.ts`
+- **Parameters:**
+  - `uri` (string, required): The URI of the MCP resource to read.
+- **Behavior:**
+  - Locates the resource and its associated server by URI.
+  - Calls the server's `resources/read` method.
+  - Processes the response, extracting text or binary data.
+- **Output (`llmContent`):** The content of the resource. For binary data, it
+  returns a placeholder indicating the data type.
+- **Confirmation:** No. This is a read-only retrieval tool.

docs/tools/mcp-server.md

@@ -64,7 +64,8 @@ Gemini CLI supports three MCP transport types:
 
 Some MCP servers expose contextual “resources” in addition to the tools and
 prompts. Gemini CLI discovers these automatically and gives you the possibility
-to reference them in the chat.
+to reference them in the chat. For more information on the tools used to
+interact with these resources, see [MCP resource tools](mcp-resources.md).
 
 ### Discovery and listing
 

integration-tests/mcp-list-resources.responses

@@ -0,0 +1,2 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"list_mcp_resources","args":{}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":10,"totalTokenCount":20}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"Here are the resources: test://resource1"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":10,"totalTokenCount":20}}]}

integration-tests/mcp-read-resource.responses

@@ -0,0 +1,2 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"read_mcp_resource","args":{"uri":"test://resource1"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":10,"totalTokenCount":20}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"The content is: content of resource 1"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":10,"totalTokenCount":20}}]}

integration-tests/mcp-resources.responses

@@ -0,0 +1,4 @@
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"list_mcp_resources","args":{}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":10,"totalTokenCount":20}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"Here are the resources: test://resource1"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":10,"totalTokenCount":20}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"functionCall":{"name":"read_mcp_resource","args":{"uri":"test://resource1"}}}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":10,"totalTokenCount":20}}]}
+{"method":"generateContentStream","response":[{"candidates":[{"content":{"parts":[{"text":"The content is: content of resource 1"}],"role":"model"},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":10,"candidatesTokenCount":10,"totalTokenCount":20}}]}

integration-tests/mcp-resources.test.ts

@@ -0,0 +1,178 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { TestRig } from './test-helper.js';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fs from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+describe('mcp-resources-integration', () => {
+  let rig: TestRig;
+
+  beforeEach(() => {
+    rig = new TestRig();
+  });
+
+  afterEach(async () => await rig.cleanup());
+
+  it('should list mcp resources', async () => {
+    await rig.setup('mcp-list-resources-test', {
+      settings: {
+        model: {
+          name: 'gemini-3-flash-preview',
+        },
+      },
+      fakeResponsesPath: join(__dirname, 'mcp-list-resources.responses'),
+    });
+
+    // Workaround for ProjectRegistry save issue
+    const userGeminiDir = join(rig.homeDir!, '.gemini');
+    fs.writeFileSync(join(userGeminiDir, 'projects.json'), '{"projects":{}}');
+
+    // Add a dummy server to get setup done
+    rig.addTestMcpServer('resource-server', {
+      name: 'resource-server',
+      tools: [],
+    });
+
+    // Overwrite the script with resource support
+    const scriptPath = join(rig.testDir!, 'test-mcp-resource-server.mjs');
+    const scriptContent = `
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListResourcesRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+const server = new Server(
+  {
+    name: 'resource-server',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      resources: {},
+    },
+  },
+);
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: 'test://resource1',
+        name: 'Resource 1',
+        mimeType: 'text/plain',
+        description: 'A test resource',
+      }
+    ],
+  };
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+`;
+    fs.writeFileSync(scriptPath, scriptContent);
+
+    const output = await rig.run({
+      args: 'List all available MCP resources.',
+      env: { GEMINI_API_KEY: 'dummy' },
+    });
+
+    const foundCall = await rig.waitForToolCall('list_mcp_resources');
+    expect(foundCall).toBeTruthy();
+    expect(output).toContain('test://resource1');
+  }, 60000);
+
+  it('should read mcp resource', async () => {
+    await rig.setup('mcp-read-resource-test', {
+      settings: {
+        model: {
+          name: 'gemini-3-flash-preview',
+        },
+      },
+      fakeResponsesPath: join(__dirname, 'mcp-read-resource.responses'),
+    });
+
+    // Workaround for ProjectRegistry save issue
+    const userGeminiDir = join(rig.homeDir!, '.gemini');
+    fs.writeFileSync(join(userGeminiDir, 'projects.json'), '{"projects":{}}');
+
+    // Add a dummy server to get setup done
+    rig.addTestMcpServer('resource-server', {
+      name: 'resource-server',
+      tools: [],
+    });
+
+    // Overwrite the script with resource support
+    const scriptPath = join(rig.testDir!, 'test-mcp-resource-server.mjs');
+    const scriptContent = `
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+const server = new Server(
+  {
+    name: 'resource-server',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      resources: {},
+    },
+  },
+);
+
+// Need to provide list resources so the tool is active!
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: 'test://resource1',
+        name: 'Resource 1',
+        mimeType: 'text/plain',
+        description: 'A test resource',
+      }
+    ],
+  };
+});
+
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  if (request.params.uri === 'test://resource1') {
+    return {
+      contents: [
+        {
+          uri: 'test://resource1',
+          mimeType: 'text/plain',
+          text: 'This is the content of resource 1',
+        }
+      ],
+    };
+  }
+  throw new Error('Resource not found');
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+`;
+    fs.writeFileSync(scriptPath, scriptContent);
+
+    const output = await rig.run({
+      args: 'Read the MCP resource test://resource1.',
+      env: { GEMINI_API_KEY: 'dummy' },
+    });
+
+    const foundCall = await rig.waitForToolCall('read_mcp_resource');
+    expect(foundCall).toBeTruthy();
+    expect(output).toContain('content of resource 1');
+  }, 60000);
+});

packages/core/src/config/config.ts

@@ -30,6 +30,8 @@ import { ResourceRegistry } from '../resources/resource-registry.js';
 import { ToolRegistry } from '../tools/tool-registry.js';
 import { LSTool } from '../tools/ls.js';
 import { ReadFileTool } from '../tools/read-file.js';
+import { ReadMcpResourceTool } from '../tools/read-mcp-resource.js';
+import { ListMcpResourcesTool } from '../tools/list-mcp-resources.js';
 import { GrepTool } from '../tools/grep.js';
 import { canUseRipgrep, RipGrepTool } from '../tools/ripGrep.js';
 import { GlobTool } from '../tools/glob.js';
@@ -3578,6 +3580,12 @@ export class Config implements McpContext, AgentLoopContext {
     maybeRegister(WebFetchTool, () =>
       registry.registerTool(new WebFetchTool(this, this.messageBus)),
     );
+    maybeRegister(ReadMcpResourceTool, () =>
+      registry.registerTool(new ReadMcpResourceTool(this, this.messageBus)),
+    );
+    maybeRegister(ListMcpResourcesTool, () =>
+      registry.registerTool(new ListMcpResourcesTool(this, this.messageBus)),
+    );
     maybeRegister(ShellTool, () =>
       registry.registerTool(new ShellTool(this, this.messageBus)),
     );

packages/core/src/policy/policies/read-only.toml

@@ -47,7 +47,10 @@ toolName = [
   # Topic grouping tool is innocuous and used for UI organization.
   "update_topic",
   # Core agent lifecycle tool
-  "complete_task"
+  "complete_task",
+  # MCP resource tools
+  "read_mcp_resource",
+  "list_mcp_resources"
 ]
 decision = "allow"
 priority = 50

packages/core/src/policy/toml-loader.test.ts

@@ -1057,6 +1057,25 @@ priority = 100
           cliHelpResult.decision,
           'cli_help should be ALLOWED in Plan Mode',
         ).toBe(PolicyDecision.ALLOW);
+
+        // 7. Verify MCP resource tools are ALLOWED
+        const listMcpResult = await engine.check(
+          { name: 'list_mcp_resources' },
+          undefined,
+        );
+        expect(
+          listMcpResult.decision,
+          'list_mcp_resources should be ALLOWED in Plan Mode',
+        ).toBe(PolicyDecision.ALLOW);
+
+        const readMcpResult = await engine.check(
+          { name: 'read_mcp_resource', args: { uri: 'test://resource' } },
+          undefined,
+        );
+        expect(
+          readMcpResult.decision,
+          'read_mcp_resource should be ALLOWED in Plan Mode',
+        ).toBe(PolicyDecision.ALLOW);
       } finally {
         await fs.rm(tempPolicyDir, { recursive: true, force: true });
       }

packages/core/src/tools/definitions/base-declarations.ts

@@ -137,3 +137,7 @@ export const TOPIC_PARAM_STRATEGIC_INTENT = 'strategic_intent';
 // -- complete_task --
 export const COMPLETE_TASK_TOOL_NAME = 'complete_task';
 export const COMPLETE_TASK_DISPLAY_NAME = 'Complete Task';
+
+// -- MCP Resources --
+export const READ_MCP_RESOURCE_TOOL_NAME = 'read_mcp_resource';
+export const LIST_MCP_RESOURCES_TOOL_NAME = 'list_mcp_resources';

packages/core/src/tools/definitions/coreTools.ts

@@ -43,6 +43,8 @@ export {
   UPDATE_TOPIC_DISPLAY_NAME,
   COMPLETE_TASK_TOOL_NAME,
   COMPLETE_TASK_DISPLAY_NAME,
+  READ_MCP_RESOURCE_TOOL_NAME,
+  LIST_MCP_RESOURCES_TOOL_NAME,
   // Shared parameter names
   PARAM_FILE_PATH,
   PARAM_DIR_PATH,
@@ -280,3 +282,17 @@ export function getActivateSkillDefinition(
     overrides: (modelId) => getToolSet(modelId).activate_skill(skillNames),
   };
 }
+
+export const READ_MCP_RESOURCE_DEFINITION: ToolDefinition = {
+  get base() {
+    return DEFAULT_LEGACY_SET.read_mcp_resource;
+  },
+  overrides: (modelId) => getToolSet(modelId).read_mcp_resource,
+};
+
+export const LIST_MCP_RESOURCES_DEFINITION: ToolDefinition = {
+  get base() {
+    return DEFAULT_LEGACY_SET.list_mcp_resources;
+  },
+  overrides: (modelId) => getToolSet(modelId).list_mcp_resources,
+};