Google Drive for AI Agents: Scope It to Picked Files

The boundary should be a file selection

The useful permission boundary for Drive-backed agent work is the file the user chose, not the account the user owns. An agent helping summarize a contract, compare a product spec or answer questions about a spreadsheet usually needs a small set of documents. It does not need every shared drive, every personal file, old exports, meeting notes, finance folders and private drafts that happen to be reachable by the signed-in account.

Google's own Drive guidance points in that direction. It recommends choosing the most narrowly focused scope possible, and it describes https://www.googleapis.com/auth/drive.file as the non-sensitive scope for files the app creates, opens, or receives through Google Picker or an app file picker. The same page lists drive and drive.readonly as restricted scopes that cover all Drive files. For an agent connector, that distinction matters because model mistakes and accidental retrieval both get worse when the backing credential can see the entire corpus.

Design the connector so the user first picks files in a normal Drive selection flow. The agent then sees a tool surface scoped to those file IDs. If the agent asks for something outside that set, the correct result is not a best-effort search across Drive. It is a clear permission error that tells the user to add the file explicitly.

What the picker stores

Google Picker is the user interface for choosing Drive files without leaving the application. Its API returns specific file metadata after selection, including identifiers and URLs. That picker result should become the connector's allowlist. Store the Google file ID, display name, MIME type, owner or shared-drive context if needed for auditing, and the workspace user who made the selection. Do not store a broad query like folder:legal and do not infer that nearby files are also approved.

A compact internal record is enough for most agent flows:

{
  "source": "google-drive",
  "picked_by_user_id": "usr_123",
  "files": [
    {
      "file_id": "1AbC...",
      "name": "Vendor MSA.pdf",
      "mime_type": "application/pdf",
      "picked_at": "2026-10-14T09:30:00Z"
    }
  ]
}

The important part is that the tool implementation checks this table on every call. A tool argument containing a Drive file ID is not proof of authorization. It is just input. The connector should verify that the file ID is still in the picked set for the workspace, source and caller before it downloads, exports or reads metadata.

Expose tools that cannot wander

The MCP tool layer should make the boundary obvious to the model. Avoid a tool named search_drive if it can be read as "search everything this user can access." Prefer names and descriptions that say selected files, picked files or attached files. This is not just copywriting. MCP clients discover tools with JSON-RPC tools/list, and the model sees the tool name, description and input schema before it chooses what to call. A vague tool teaches the model to try broad retrieval.

A safer tool set is small and boring:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

{
  "tools": [
    {
      "name": "drive.list_picked_files",
      "description": "List only the Google Drive files explicitly picked for this workspace source.",
      "inputSchema": { "type": "object", "additionalProperties": false }
    },
    {
      "name": "drive.read_picked_file",
      "description": "Read text from one picked Google Drive file by file_id. Fails if the file was not picked.",
      "inputSchema": {
        "type": "object",
        "properties": { "file_id": { "type": "string" } },
        "required": ["file_id"],
        "additionalProperties": false
      }
    }
  ]
}

That design also helps review and logging. A call to drive.read_picked_file has one authorization question: is this exact file ID in the selected set? A call to drive.search has many hidden questions about query syntax, inherited permissions, shared drives and how much context the tool returns.

OAuth scope is not the whole policy

The OAuth grant and the connector policy have different jobs. The Drive OAuth scope limits what Google's API token can do. The connector's own allowlist limits what the agent can do with that token inside the workspace. You want both. If either layer is too broad, the resulting agent surface is too broad.

For most user-picked workflows, request drive.file and drive the sharing decision through Picker. Do not ask for drive.readonly just because the agent might someday need another file. If the user wants the agent to read another file, make that a visible file-picking action. The friction is useful because it turns data access into an explicit choice instead of an invisible side effect of sign-in.

MCP authorization reinforces the same separation. A protected MCP server can use OAuth-style authorization, and tool access can vary with the authorization presented on the request. That means the MCP server can expose a stable connector while still enforcing which workspace, source and permission grant is attached to the caller. In practice, the Drive token should never be handed to the agent. The agent calls a tool; the server checks the workspace policy; the connector calls Drive only if the picked-file rule passes.

Failure cases to handle deliberately

Picked-file access has a few sharp edges that are worth designing as first-class cases. First, the file can disappear. A user may remove the app's access, move the file, delete it or lose access through a shared-drive permission change. The tool should return a clear execution error for that file, not silently search for a similar filename.

Second, filenames are not stable authorization handles. Two files can have the same name, and names can be changed after selection. Use Drive file IDs for calls and show names only as human-readable labels. Third, file type affects the read path. A PDF, a Google Doc and a Sheet may require different export or extraction behavior, so expose either a single tool with explicit MIME-type handling in its result or separate narrow tools with descriptions the model can follow.

Finally, revoke cleanly. Removing a picked file from the connector should make future calls fail even if the model copied the old ID into its notes. Removing the whole Drive source should invalidate every file in that source. These are ordinary product details, but they are the details that keep a picked-file model honest after the initial OAuth flow succeeds.

Doing this through SPYN3

SPYN3's Google Drive connector uses the Google Picker: the person connecting chooses files, and only those files are visible to the agent. The OAuth scope does not reach the rest of the Drive. The agent gets two read-only tools, list_files and read_file, under the connector's folder. Adding a file later means picking it in the dashboard, not widening a scope.

A practical rollout checklist

1. Use Picker or an equivalent explicit file-selection flow before the agent can read Drive content.
2. Request drive.file for picked-file workflows, and document why any broader Drive scope is required before approving it.
3. Persist selected file IDs as an allowlist, with the user, workspace, source and timestamp.
4. Expose MCP tools with names that say picked, selected or attached files, and require file_id arguments for reads.
5. Authorize every tool call against the allowlist before calling the Drive API.
6. Log the tool name, file ID, caller key, result status and timing so access can be audited later.
7. Make revocation boring: removing a file from the source should immediately make future calls against that ID fail.

This pattern pairs well with broader integration decisions. If you are deciding how much authority a key should have, read scoping API keys for AI agents. If you need to separate read-only and write-capable tools across sources, the companion guide on read-only vs write MCP tools covers the permission model.