Troubleshooting
Gmail reconnect
The Gmail MCP connection typically drops when the service account key is rotated, domain-wide delegation is revoked, or the Gmail API is disabled. Follow the steps below to reconnect.
Signs of a dropped Gmail connection
- !The Operator created an escalation card mentioning gmail.
- !The activation checklist shows the Support MCP step as red.
- !No Support reply drafts are appearing despite new customer emails.
- !claude mcp list shows gmail as error or disconnected.
Step 1: Check the error
claude mcp listNote the error message next to gmail. The most common errors are:
invalid_grant
The service account credentials are expired or invalid. Proceed to Step 2a.
access_denied
Domain-wide delegation was revoked. Proceed to Step 2b.
disabled
The Gmail API is disabled for the Google Cloud project. Proceed to Step 2c.
Step 2a: Rotate the service account key
- Go to Google Cloud Console → IAM & Admin → Service Accounts.
- Find the FlostackOS service account.
- Open it → Keys tab → Add key → Create new key → JSON.
- Download the new credentials file and store it securely.
- Delete the old key from the Keys tab.
claude mcp add gmail --service-account /path/to/new-credentials.json --email you@yourdomain.comStep 2b: Restore domain-wide delegation
- Go to Google Workspace Admin → Security → API controls → Domain-wide delegation.
- Find or add the FlostackOS service account client ID.
- Ensure the scope https://www.googleapis.com/auth/gmail.readonly is listed.
- Save. Delegation takes effect within a few minutes.
The service account client ID is shown on the service account detail page in Google Cloud Console under the Unique ID field.
Step 2c: Re-enable the Gmail API
- Go to Google Cloud Console → APIs & Services → Library.
- Search for Gmail API.
- Click Enable.
Step 3: Verify
claude mcp listThe gmail entry should show as connected. The Operator will update the activation checklist on its next run, every 2 hours.