# Connect Google to Aerostack

> Set up your own Google OAuth app, connect once, and unlock Gmail, Drive, Calendar, Sheets, Docs across every Google MCP. ~5 minutes, no billing required.

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

1. **Open Google Cloud Console**

   Go to [console.cloud.google.com](https://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.
   

1. **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.
   

1. **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.
   

1. **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.
   

1. **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

1. **Open Connections**

   In Aerostack: **Workspaces** → your workspace → **Connections** tab.

1. **Click "Connect" on the Google (Custom) tile**

   Find **Google (Custom)** in the **Available to Connect** grid → **Connect**.

1. **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**.

1. **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

1. **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.

1. **Run "Diagnose All"**

   **Workspaces** → your workspace → **Settings** → **Diagnose All**. The Google MCP should show ✅ green with N tools available.

1. **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](https://myaccount.google.com/permissions) for full revocation)