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.

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.

Field	Value
Project name	`Aerostack` (or any name — only you see it)
Organization	Leave default (“No organization” is fine)

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.

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.
Caution
- “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.)

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

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`

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.com value
- Client Secret → paste the GOCSPX-xxxxxxxxxxxxxxxxxx value
- 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 (you@gmail.com) 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)