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:

Result	Meaning	Action
Success (doc/presentation created)	Auth is valid	Report "Auth: OK", clean up test resource, proceed
401 Unauthorized	Token expired/invalid	Proceed to Step 4 (re-auth)
403 Forbidden (when creating)	Quota exceeded or API disabled	Report API configuration issue
"Tool not found"	MCP not loaded	Recommend restarting Claude Code
"Address already in use"	OAuth server already running	Try actual API call (ignore this error)

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

Step 5: Verify After Re-auth

After user confirms auth completed, repeat Step 3 (create test document/presentation).

If successful:

Auth: OK ({server_type})
Re-authentication successful
Proceeding with {original_task}

If still failing: Check diagnostics:

# Verify new credentials appeared
ls ~/.claude/mcp-servers/google-docs-mcp-server/

# Check if token was actually written
ls -lh ~/.claude/mcp-servers/google-docs-mcp-server/token.json

# If token is 0 bytes or very old (unchanged timestamp), auth didn't complete

If credentials still missing/invalid:

Auth: FAILED — Re-authentication did not create valid credentials

Diagnostic findings:
- Credential location: {path_checked}
- Token file: {exists/missing}
- Token size: {bytes} (should be >200 bytes)
- Last modified: {timestamp}

Recommended action:
1. Restart Claude Code (closes all MCP servers cleanly)
2. Check for auth URL in Claude Code startup logs
3. Complete OAuth flow in browser
4. Verify you added your email as a test user in Google Cloud Console
5. If still failing, check Google Cloud Console → APIs & Services → Enabled APIs
   - Required: Google Docs API, Google Drive API (and Google Slides API if needed)

Step 6: Cleanup Test Resources (Optional)

If you created a test document/presentation in Step 3 and it's still accessible, optionally clean it up:

# For test documents
mcp__google-docs__delete_document(document_id="{test_doc_id}")
# (if delete tool exists)

# Or just leave it - user can delete manually from Drive

This is non-critical; the test resource causes no harm.

---

Known Issues & Solutions

Issue	Symptom	Root Cause	Fix
Email mismatch (workspace-mcp)	Auth succeeds but all API calls fail with "Invalid grant"	Email parameter doesn't match credential filename exactly	Extract email from credential filename, use exact string (including/excluding dots)
Token expired	"Authentication needed" on every call	Token hasn't been refreshed, or refresh token invalid	Re-auth via Step 4
App not verified	"Access blocked" screen after selecting Google account	User not added as test user for OAuth app	Add user's email in Google Cloud Console → OAuth consent screen → Test users
URL corruption	Auth URL gives 400 error	Terminal cmd-click appended control characters	Copy-paste URL manually, don't click
MCP server not found	"Tool not found" errors on all MCP calls	Server didn't start with Claude Code session	Restart Claude Code (MCP servers auto-start)
Port conflict	"Address already in use" during authorize()	OAuth callback server already bound to port	Restart Claude Code to reset server state
Stale token in memory	Credentials valid on disk but API calls fail	MCP server has cached invalid token	Restart Claude Code to reload credentials from disk
Credentials in wrong location	Token.json exists but skill can't find it	Custom MCP installation path	Check .mcp.json command/args to infer storage location

General troubleshooting principle: When in doubt, restart Claude Code. This cleanly reloads all MCP servers with fresh credentials from disk.

---

Implementation Patterns by MCP Type

Pattern A: google-workspace MCP (workspace-mcp package)

• Credentials: ~/.google_workspace_mcp/credentials/{email}.json
• Email required: Yes — passed to every API call as user_google_email parameter
• Email format: EXACT string from filename (e.g., john.doe@gmail.com ≠ johndoe@gmail.com)
• Test call: create_doc() with email + title
• Re-auth: mcp__google-workspace__authorize()

Pattern B: google-docs MCP (custom Python server)

• Credentials: ~/.claude/mcp-servers/google-docs-mcp-server/token.json
• Email required: No — token is user-agnostic
• Test call: create_document(title="...") — no email param
• Re-auth: mcp__google-docs__authorize_google_docs()
• Token contents: JSON with token, refresh_token, expiry, scopes

Pattern C: google-slides MCP

• Credentials: ~/.claude/mcp-servers/google-slides-mcp-server/token.json
• Email required: No
• Test call: create_presentation(title="...")
• Re-auth: mcp__google-slides__authorize()

Adaptation rule: Always detect actual config from .mcp.json and ls results rather than assuming a specific pattern. Support all three patterns in the same skill.

---

Rules

1. Always use CREATE for test calls, never READ. Creating a resource only requires valid auth. Reading requires auth + permissions on that specific resource.

2. Extract email from credential filename for workspace-mcp. Don't ask the user for their email. The exact string in the filename is what must be passed to API calls.

3. One auth attempt, then clear explanation. If re-auth fails, provide diagnostics and actionable next steps. Don't retry repeatedly.