Google Drive (Reliable)

gdrive-cowork-connector

Self-hosted remote MCP server plus Cowork/Claude plugin for reliable Google Drive access where Anthropic's bundled connector fails.

Operator guide — server setup & Cowork install

End-to-end path for operators who deploy this MCP server and distribute a Cowork / Claude plugin bundle (see P-07 in docs/prd.md). Canonical infrastructure tables, WIF, Redis, and Epic 0 checklists live in docs/environments.md — this section ties them to concrete steps.

Operator guide = this README + docs/environments.md. On-call playbooks: docs/runbooks/README.md. MCP Inspector (CLI tools/list smoke): scripts/mcp-inspector-validate.sh (set MCP_INSPECTOR_URL if not using the default http://127.0.0.1:8080/mcp).

1. Google Cloud OAuth client

1. In a GCP project, enable the Google Drive API (APIs & Services → Library).
2. Credentials → Create credentials → OAuth client ID → Web application.
3. Under Authorized redirect URIs, add at least https://claude.ai/api/mcp/auth_callback so hosted Claude / Cowork can complete OAuth (docs/architecture.md OAuth section). If you support Claude Code, also register the loopback redirect URIs your MCP client registration flow uses (see docs/ux.md and docs/brief.md).
4. Record Client ID and Client secret — they map to GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in env.example. Store real values only in Secret Manager or a locked secret store, never in git.

2. Secrets, issuer URL, and Cloud Run

• Mirror every required variable from env.example into Google Secret Manager using the same secret id as env var name, then reference each secret on the Cloud Run service (see docs/environments.md#secret-manager-staging).
• Set PUBLIC_ISSUER_URL to the HTTPS origin clients use to reach this service (e.g. https://gdrive-mcp-staging-xxxxx.run.app), no path — OAuth discovery (/.well-known/oauth-authorization-server) is derived from that issuer.
• SESSION_SECRET: generate with openssl rand -hex 32 per environment.
• Default deployment is Cloud Run in the project/region you chose; follow Bootstrapping checklist (Epic 0) for Artifact Registry, Memorystore + VPC connector (staging/prod sessions), and Workload Identity Federation for GitHub Actions.

Build & deploy (summary): from the repo root, docker build using the Dockerfile, push to Artifact Registry, then gcloud run deploy (or rely on CI: when repository secrets GCP_WORKLOAD_IDENTITY_PROVIDER, GCP_SERVICE_ACCOUNT, and GCP_ARTIFACT_REGISTRY are set, ci.yml builds and can push images — see CI — Artifact Registry push below). Map secrets to env vars on the revision.

3. Smoke-check the running service

Replace $ORIGIN with your public HTTPS origin (same value you used for PUBLIC_ISSUER_URL):

curl -fsS "$ORIGIN/healthz"
curl -fsS "$ORIGIN/.well-known/oauth-authorization-server" | head

After deploy, release.yml also exercises /__smoke/mcp-tools-list against prod when you cut a tag (see Prod release below).

Runbooks & MCP Inspector (S5.4)

• Alert runbooks — indexed under docs/runbooks/README.md; each alert in docs/observability.md links its playbook from the table.
• Inspector validation — with the server running (pnpm dev or staging URL), run:

bash scripts/mcp-inspector-validate.sh
# or: MCP_INSPECTOR_URL=https://your-host/mcp bash scripts/mcp-inspector-validate.sh

Uses npx @modelcontextprotocol/inspector in CLI mode (--transport http --method tools/list). Same command is wired as pnpm inspector:validate (see package.json).

Latency SLO (NF-02 / S5.2)

• Dashboard: import infra/observability/latency-dashboard.json into Cloud Monitoring (steps in infra/observability/README.md).
• Staging load gate: with the service reachable, run node scripts/synthetic-mcp-latency.mjs (defaults: 100 RPS for 30 s, LOAD_TEST_BASE_URL override). Exit code 1 means client-side p95 > 3 s — investigate before promoting.

Indirect prompt injection (S5.3)

Drive content can carry indirect prompt-injection risk. Read docs/security/indirect-prompt-injection.md for the threat model, how destructiveHint / readOnlyHint are used on MCP tools, and operator practices (see also docs/prd.md §8).

4. Plugin bundle for Cowork (P-05)