Google Workspace

On SynapseOrch Cloud there is nothing to set up in Google Cloud — see Connecting Google Workspace. This page is for self-hosted installs, which bring their own OAuth client.

Setup

Step 1 — Create a Google Cloud OAuth app

1. Go to console.cloud.google.com and create a project
2. Enable the APIs you need — Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks and People (for contacts). The Quick setup guide in SynapseOrch has a one-click link that enables them all.
3. Create an OAuth client ID (direct link) and choose Web application
4. Under Authorised redirect URIs, add http://localhost:8765/auth/callback — with your port if SYNAPSE_BACKEND_PORT is not 8765
5. Download the credentials JSON

The redirect URI's host is always localhost. Google sends your browser there after you sign in, so do the sign-in in a browser that reaches the SynapseOrch backend as localhost — on the same machine, or through a tunnel to the backend port.

Step 2 — Paste credentials into SynapseOrch

Go to Settings → Integrations. On the Google Workspace card, click + Paste credentials.json content, open the downloaded file, and paste its whole content. It is saved as soon as it is valid JSON. There is no file upload.

To change the client later, use Replace / re-upload credentials.json.

Step 3 — Authenticate

Click Connect Google account. Google's sign-in page opens; approve the requested access. Google then returns you to SynapseOrch's Chat screen — open Settings → Integrations again to see Authenticated and the account's email.

Restart SynapseOrch after connecting for the first time, or after changing the account or the credentials. The Google Workspace server is started when SynapseOrch starts, and only if credentials are saved; it needs uvx (uv) on the host.

If you already hold a token for this client, Advanced: import existing token JSON (skip OAuth) accepts it instead of the sign-in.

Step 4 — Available tools

The Google Workspace server is the open-source workspace-mcp package, started for Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks and Contacts. It provides a few dozen tools — searching and reading mail, sending and drafting messages, listing and changing calendar events, searching and reading Drive files, reading and editing Docs and Sheets, and more.

The exact tool names come from that package and can change between its releases. To see them, open an agent's Tools section and expand Google Workspace. The tools reach only agents that are given them there, or that have an all tool list.

Example agent prompts

Check my calendar for tomorrow and summarise the meetings.

Read the latest 5 emails with subject "invoice" and extract the amounts into a spreadsheet.

Create a Google Doc with the draft report.

Token storage

The OAuth client and the token are stored in SynapseOrch's database (as google_client and google_token), and the account's email as the google_account_email setting. Just before the Google Workspace server starts, they are written to a temporary folder that the server reads; nothing there needs backing up.

The token is renewed when SynapseOrch starts, if it has expired. If the connection is lost, go to Settings → Integrations and click Reconnect (or Connect Google account, if no account email is known), then restart SynapseOrch.

Required scopes

SynapseOrch requests these scopes:

• openid, userinfo.email, userinfo.profile — to identify the account
• gmail.modify, gmail.send, gmail.settings.basic
• drive
• calendar
• documents
• spreadsheets
• presentations
• forms.body, forms.body.readonly, forms.responses.readonly
• tasks
• contacts

each under https://www.googleapis.com/auth/ except openid. The list is fixed in SynapseOrch's code. If you grant fewer on Google's consent screen, SynapseOrch still connects, and the tools that need a missing scope fail when called.