Auth Preflight

Skill: Auth Preflight

Purpose

Verify Google Workspace MCP authentication BEFORE beginning any Google-dependent work. Catches auth issues in <30 seconds instead of discovering them after 5-10 minutes of chart generation, narrative writing, or deck building.

Core principle: Fail fast with clear guidance, not slow with cryptic errors mid-workflow.

When to Apply

Trigger this skill immediately when:

• The task involves Google Docs, Slides, or Drive
• Any mcp__google-* tool will be called
• The user mentions "Google Doc", "Google Slides", "upload to Drive", "create a deck", "export to Google", "share on Drive"
• Before running google-slides-creator, google-slides-reviewer, gdoc-builder, or any Google-dependent agent

Critical timing: Run auth preflight as your FIRST action, before exploring data, generating charts, parsing narratives, or any other substantive work.

Preflight Workflow

Step 1: Detect MCP Configuration

Read .mcp.json to discover which Google MCP server(s) are configured:

cat .mcp.json | grep -A3 google

Look for entries like:

• google-docs → Google Docs + Drive MCP server (most common)
• google-workspace → Full workspace MCP (Docs, Slides, Drive)
• google-slides → Slides-specific MCP server

Extract:

• Server name (JSON key, e.g., "google-docs")
• Command path (where the executable lives)
• Args (to identify server type)

Why this matters: Different MCP implementations store credentials in different locations. Detecting configuration first ensures you check the right paths.

If no Google MCP found: Report:

Auth: FAILED — No Google MCP server configured in .mcp.json
To use Google Docs/Slides, add a Google MCP server to .mcp.json

Step 2: Check Stored Credentials

Based on MCP type from Step 1, check credentials in ALL possible locations (some setups use non-standard paths):

Priority 1: MCP-specific locations

# For google-docs MCP
ls ~/.claude/mcp-servers/google-docs-mcp-server/

# For google-workspace MCP
ls ~/.google_workspace_mcp/credentials/

# For google-slides MCP
ls ~/.claude/mcp-servers/google-slides-mcp-server/

Priority 2: Alternative locations (check if Priority 1 empty)

# Some custom MCP installs use these
ls ~/.config/google-docs-mcp-server/
ls ~/.google_mcp/credentials/

Look for:

• token.json (current access/refresh token)
• credentials.json (OAuth client credentials)
• For workspace-mcp: {email}.json files

If no credentials found anywhere:

• Auth has never been completed
• Skip to Step 4 (Re-authenticate)

If credentials found:

• For workspace-mcp: Extract email from filename (e.g., user@gmail.com.json → use exactly user@gmail.com in all API calls)
• For other servers: Note the token.json location for diagnostics
• Check token expiry if readable: cat {token_path} | grep expiry
• Proceed to Step 3

Step 3: Test with Lightweight API Call

Make a simple API call to verify the token works. Always use CREATE operations, not READ operations to avoid permission errors on specific documents.

Best practice: Use create operations

Why create, not read? Reading a specific document can fail with 403 "Permission denied" even when auth is valid (if that doc isn't shared with the user). Creating a new document only requires valid auth, not document-specific permissions.

Test calls by MCP type:

If google-docs MCP:

mcp__google-docs__create_document(title="Auth Preflight Test - Delete Me")

• Success → Extract document_id, report "Auth: OK (google-docs)", optionally clean up test doc
• Auth error (401/403) → Proceed to Step 4
• Tool not found → Report ".mcp.json has google-docs but tools not available - restart Claude Code"

If google-workspace MCP:

mcp__google-workspace__create_doc(
    user_google_email="{email_from_credentials_filename}",
    title="Auth Preflight Test"
)

Critical: Use the EXACT email string from the credential filename. Gmail treats dots as equivalent (a.b@gmail.com = ab@gmail.com) but MCP stores tokens by exact string match.

If google-slides MCP:

mcp__google-slides__create_presentation(title="Auth Preflight Test")

Interpreting results:

If successful:

Auth: OK ({server_type})
Token verified via create_document at {timestamp}
Ready to proceed with Google API operations

If auth error: Proceed to Step 4.

Step 4: Re-authenticate

If credentials missing or token invalid, guide user through re-authentication.

Invoke appropriate auth tool:

For google-docs MCP:

mcp__google-docs__authorize_google_docs()

For google-workspace MCP:

mcp__google-workspace__authorize()

For google-slides MCP:

mcp__google-slides__authorize()

Present these instructions:

When authorization URL appears:

1. Copy-paste the URL into your browser

   • Do NOT cmd-click or ctrl-click the URL in the terminal
   • Terminal click handlers can append garbage characters that break the URL
   • Manually select, copy (Cmd+C), and paste into browser

2. Select your Google account when prompted

3. If you see "Access blocked: This app isn't verified":

   • Go to console.cloud.google.com → APIs & Services → OAuth consent screen
   • Scroll to "Test users" section → Click "Add Users"
   • Add your email address
   • Return to the auth URL and try again
   • The app will now recognize you as an authorized test user

4. If authorization fails with "Address already in use":

   • This means the MCP server is already running (normal state)
   • The issue is that no auth URL is being displayed
   • Solution: Restart Claude Code completely
   • The MCP server will restart and display the auth URL on startup

5. After you see "Authentication successful" in browser, tell me "done" and I'll verify