Google Drive Agentic Retrieval MCP

Read-only agentic retrieval over Google Drive and Google Docs/Sheets/Slides, served by a stateless MCP on Cloud Run, for any MCP-compatible reasoning agent.

This repository is developed with Spec-Kit spec-driven development. Governing principles live in .specify/memory/constitution.md and bind every subsequent spec, plan, task list, and implementation.

Constitution (ratified v1.0.0)

Google Drive is the sole source of truth. The MCP is a secure, deterministic, ephemeral evidence-acquisition layer. The calling agent owns reasoning and the retrieval loop. v1 is read-only, single Google identity per deployment, and does not require an application-owned RAG index.

See the constitution for the full invariant set (Articles I–XV).

Related MCP server: mcp-server-drive

Connecting ChatGPT / Claude / Cursor

This is standard MCP Streamable HTTP (POST /mcp). The host model — not this server — parses the user question and chooses drive_ls / drive_find / drive_read / drive_grep arguments. tools/list advertises when to use each tool and positive/negative examples.

Auth: MCP OAuth 2.1 on this origin (authorization code + PKCE, dynamic client registration, protected-resource metadata). Hosts send Authorization: Bearer <access_token> on POST /mcp. Public Cloud Run auto-approves the OAuth redirect (no /consent password). MCP_AUTH_TOKEN is still not an API key.

Add this connector in Claude

Read-only Google Drive tools. This server cannot write, delete, or share. Claude still has two prompts this origin cannot skip: Always allow, and enabling the connector in a chat.

Connector URL

https://onto-kb-kxjtmypvfa-uc.a.run.app/mcp

The same steps are on one page: https://onto-kb-kxjtmypvfa-uc.a.run.app/setup.

1. Claude Web → Customize → Connectors → + → Add custom connector.

2. Name: onto-kb. Paste the URL above.

3. Authentication: Sign in when needed (override Detected “No sign-in” if shown). OAuth client: Use Claude’s published identity. Leave request headers empty.

4. Connect. Your browser returns to Claude. There is no deployment password.

5. When Claude asks Read-only tools, always allow?, choose Always allow.

6. In a chat, + → Connectors → enable onto-kb.

Knowing the connector URL is enough to finish OAuth. Drive calls still require the short-lived token Claude stores after Connect. Do not put MCP_AUTH_TOKEN in Claude request headers.

Tool results identify files with file_id and source_url as drive:{file_id} — not an HTTPS Drive link — so Cited Sources cannot offer a download. Document text is still returned as evidence; use drive_read for the body.

Do not put tokens in the MCP URL or in tool arguments. Do not send MCP_AUTH_TOKEN as the /mcp Bearer.

Non-PII usage totals (Connect completions and first Drive tool use — not unique people): https://onto-kb-kxjtmypvfa-uc.a.run.app/stats. The same numbers appear on /setup.

In GCP: Logs (oauth_connect), Metrics Explorer (logging.googleapis.com/user/onto_kb_oauth_connects and onto_kb_drive_first_uses), and dashboard onto-kb connect counter under Monitoring dashboards. Cloud Run’s own Metrics tab is only request/latency/error.

Spec-Driven Development

Cursor skills are installed under .cursor/skills/. Use them in this order:

1. /speckit-constitution — project principles (done: v1.0.0)

2. /speckit-specify — what to build (done: access control + retrieval core + connect counter)

3. /speckit-clarify — optional; de-risk underspecified areas (done: session 2026-09-08)

4. /speckit-plan — how to build it (done: access control + retrieval core + connect counter)

5. /speckit-tasks — actionable implementation tasks (done: access control, retrieval core, connect counter)

6. /speckit-analyze — optional; cross-artifact consistency (done: 2026-09-08; remediations and plan sync applied)

7. /speckit-implement — execute the tasks

8. /speckit-converge — compare the codebase to spec/plan/tasks and append remaining work

Feature specs (ready for implementation):

• Access Control Boundary — who may act, and on what authority

• Retrieval Core — discover, read, exact-search once a call is cleared

• Non-PII Connect Counter — Connect and first Drive-use counts on /stats and the GCP dashboard onto-kb connect counter

Repeat implement and converge until converge reports Converged.

The Specify CLI (specify-cli 1.0.4) initialized this project with the cursor-agent integration and bash scripts. Refresh managed files with specify integration upgrade after upgrading the CLI.

Shared pickup state for the next Cloud Agent:

• .specify/memory/project-status.md — current SDD phase

• .cursor/rules/spec-kit-sdd.mdc — always-on constitution and next-step rules

• .cursor/environment.json — installs uv and specify-cli on Cloud Agent boot

Out of v1 scope

Multi-tenant access, write capability, persistent caches, and semantic/vector retrieval are MAJOR constitutional changes (Article XIV) and MUST be specified before any implementation work.