Connect Google to Aerostack
Connect your Google account once. Every Google MCP — Gmail, Drive, Calendar, Sheets, Docs — works automatically afterwards. Tokens auto-refresh forever; no per-app setup, no manual re-pasting.
Total time: ~5–7 minutes, one time. Cost: free (no billing required for Gmail / Drive / Calendar / Sheets / Docs APIs at personal-use volumes).
Why “Bring Your Own” OAuth?
Google requires apps to go through a verification process before they can access sensitive scopes (Gmail, Drive, Calendar) for arbitrary users. That verification takes 4–8 weeks for the publisher (us).
Workaround that works today: you create your own Google OAuth app — which only your account uses — and plug its credentials into Aerostack. Because you are the developer of your app, no verification is needed for your personal use. Up to 100 test users supported.
This is the same pattern n8n, Make, Pipedream, and Retool use. Once Aerostack publishes a verified Google app (planned), you can switch to that with one click — but BYO will remain available for power users who want their own quota and full control.
Part 1 — Create your Google OAuth app
Open Google Cloud Console
Go to console.cloud.google.com and sign in with the Google account whose Gmail / Drive / Calendar you want Aerostack to access.
Multiple Google accounts? Pick the right one from the top-right avatar before continuing — you can’t change it later without redoing the OAuth client.
Create a new project
Top bar → click the project selector (shows current project name or “Select a project”) → New Project (top-right of the modal).
| Field | Value |
|---|---|
| Project name | Aerostack (or any name — only you see it) |
| Organization | Leave default (“No organization” is fine) |
Click Create. Wait ~5 seconds for the toast: “Creating project… Done.” — then click Select Project to switch to it.
Verify: the top bar should now show your project name.
“You have reached the maximum number of projects” → free tier caps at 12. Delete an unused project (Console → IAM & Admin → Manage Resources) or use an existing project.
Enable the APIs you need
Sidebar (☰ top-left) → APIs & Services → Library. For each Google service you plan to use, search and enable. Recommended set:
| API | Why enable |
|---|---|
| Gmail API | Read/send/search Gmail |
| Google Drive API | List/upload/download Drive files |
| Google Calendar API | Create/list calendar events |
| Google Sheets API | Read/write Sheets |
| Google Docs API | Read/write Docs |
| People API | Contacts |
For each: search → click result → click Enable → wait ~3 seconds. You can come back and add more APIs later — won’t break anything.
“Billing must be enabled” banner → ignore it. Gmail, Drive, Calendar, Sheets, Docs all work without billing at personal-use quotas. The actual Enable button on each API’s page works regardless.
Configure the OAuth consent screen
Sidebar → APIs & Services → OAuth consent screen.
User Type screen → Choose External → Create.
App information (page 1 of 4):
| Field | Value |
|---|---|
| App name | My Aerostack (only you see it) |
| User support email | Your email |
| App logo | Skip |
| Application home page / privacy / terms | Skip |
| Authorized domains | Skip |
| Developer contact email | Your email |
Click Save and Continue.
Scopes (page 2 of 4) → leave empty → Save and Continue.
Skipping is intentional. Scopes are determined per-OAuth-flow by what Aerostack requests; pre-listing here can cause “scope mismatch” errors if you forget one.
Test users (page 3 of 4) → Click + Add Users → enter every Google account that will use this OAuth app (typically just your own). Up to 100 supported. → Save and Continue.
Summary (page 4) → Back to Dashboard. Status badge shows Testing — leave it.
- “App name is invalid” → can’t contain “Google”. Use any other name.
- Test user email “Invalid” → must be a Google account (Gmail or Workspace).
- Stuck on “Authorized domains” → you skipped it; this only applies if you added domains earlier.
Create the OAuth Client credentials
Sidebar → APIs & Services → Credentials → + Create Credentials → OAuth client ID.
| Field | Value |
|---|---|
| Application type | Web application |
| Name | Aerostack |
| Authorized JavaScript origins | Skip |
| Authorized redirect URIs | Click + Add URI → paste exactly:https://auth.aerostack.dev/callback/google |
The redirect URI must match character-for-character — https://, no trailing slash, no typos. Aerostack’s connect modal will display the exact value to copy.
Click Create. A modal pops up with two values:
- Client ID:
407408718192-xxxxxxxx.apps.googleusercontent.com - Client Secret:
GOCSPX-xxxxxxxxxxxxxxxxxx
Copy both now. You’ll paste them into Aerostack next. (You can always retrieve them later from Console → Credentials → click the client name.)
Part 2 — Connect in Aerostack
Open Connections
In Aerostack: Workspaces → your workspace → Connections tab.
Click “Connect” on the Google (Custom) tile
Find Google (Custom) in the Available to Connect grid → Connect.
Paste your credentials and pick scopes
The modal asks for:
- Client ID → paste the
407408718192-xxxxxxxx.apps.googleusercontent.comvalue - Client Secret → paste the
GOCSPX-xxxxxxxxxxxxxxxxxxvalue - Scopes (checkboxes) → tick the services you enabled in Step 3:
- ☑ Gmail (read, send, modify)
- ☑ Drive (files)
- ☑ Calendar (events)
- ☐ Sheets (tick if you enabled the API)
- ☐ Docs (tick if you enabled the API)
You can re-tick more scopes later by clicking Reconnect — no need to ask for everything upfront.
Click Continue.
Authorize on Google’s side
Aerostack redirects you to Google’s consent flow. You’ll see two screens:
a) “Google hasn’t verified this app”
⚠ Google hasn't verified this app
The app is requesting access to sensitive info in your Google
Account. Until the developer ([email protected]) verifies this app
with Google, you shouldn't use it.
[ Go back to safety ]
Advanced ▼→ Click Advanced at the bottom → click Go to My Aerostack (unsafe).
This warning appears because you haven’t gone through Google’s verification — your own OAuth app is what’s “unverified”. Since it’s your app accessing your own account, you’re trusting yourself. The warning will disappear if you ever submit your app for Google verification (optional).
b) Permissions
Google shows the scopes Aerostack is requesting. Click Continue (twice — Google double-confirms sensitive scopes).
You’ll redirect back to Aerostack and Google will appear as Connected in the Connections page.
Part 3 — Verify it works
Install a Google MCP
MCP Servers → search Gmail (or Drive / Calendar) → Install.
The install modal does NOT ask for a token. Aerostack sees your Google connection and wires it up automatically.
Run “Diagnose All”
Workspaces → your workspace → Settings → Diagnose All. The Google MCP should show ✅ green with N tools available.
Try a tool call
Open Agent Chat or Playground and ask: “List my last 5 unread emails” or “What’s on my calendar tomorrow?” Real data → done.
Maintenance
| Event | What you do |
|---|---|
| Access token expires (every 1h) | Nothing. Aerostack auto-refreshes via your refresh token. |
| Install another Google MCP | Nothing. It picks up your existing connection. |
| MCP needs a scope you didn’t grant | Click the prompt → re-authorize with the new scope ticked (~30s). |
| You revoke access in Google account settings | Aerostack shows the connection as expired → click Reconnect. |
| 6+ months of zero use | Google may revoke under “inactive token” policy → Reconnect. |
Troubleshooting
| Error | Where it appears | Fix |
|---|---|---|
redirect_uri_mismatch (Error 400) | Google consent screen | Step 5 — redirect URI in Google Cloud Console must match Aerostack’s exactly. Re-copy from the modal. No trailing /, no http://. |
access_denied (Error 403) | Google consent screen | Step 4 — your Google account is not in the Test Users list. Add it in Cloud Console → OAuth consent screen → Test Users. |
invalid_client | Aerostack modal after Continue | Step 5 — re-copy Client ID and Client Secret. Watch for trailing whitespace or truncation. |
invalid_grant | Later, during a tool call | Refresh token expired. Click Reconnect in Connections. |
scope_required | Tool call result | The MCP needs a scope you didn’t grant. Reconnect with the missing scope ticked. |
| Tool call returns 403 | Agent chat | The corresponding Google API is not enabled in Cloud Console. Step 3 — enable it. |
| ”This app is blocked” | Google consent screen | Workspace admin policy restriction. Try a personal Gmail, or have your admin allow the app. |
| Stuck after consent — no redirect | URL bar shows error=... | Most often means a scope you ticked has no corresponding API enabled. Step 3 — enable it. |
| Connections page shows “1 connection · token expired” | Connections | The refresh token failed. Click Reconnect. |
When to use the Aerostack-verified app instead
You can skip BYO and wait for Aerostack’s verified Google app (rolling out later) only if all of these are true:
- You’re OK pasting OAuth Playground tokens hourly while you wait
- You don’t want to spend 5 minutes in Google Cloud Console
- Quota independence isn’t a concern
Otherwise, do the BYO setup once. After that you’ll never think about Google authentication again.
What this unlocks
After connecting Google once, every MCP listed below auto-installs without a single token paste:
@aerostack/mcp-gmail— read/send/search/label@aerostack/mcp-google-drive— list/upload/download@aerostack/mcp-google-calendar— events, scheduling@aerostack/mcp-google-sheets— read/write rows@aerostack/mcp-google-docs— create/edit docs@aerostack/mcp-google-contacts— People API- (Plus any future Google MCP — it’ll pick up the same connection.)
Security
- Tokens encrypted with AES-256-GCM in
mcp_workspace_secrets - Refresh tokens rotate via background cron in
oauth-broker - Plaintext tokens are never returned by the dashboard or API
- Tokens are scoped per-workspace, not per-user — workspace members share access
- Disconnecting deletes the encrypted secret immediately and revokes the broker token (your Google account itself is unaffected — revoke at myaccount.google.com/permissions for full revocation)