---
name: "google_connect"
area: "googleworkspace"
title: "Connect Google Workspace"
price: "free"
method: "POST"
url: "https://api.conecto.chat/v1/tools/google_connect"
mcp_server: "https://api.conecto.chat/mcp/googleworkspace"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/googleworkspace/google_connect"
---

# Connect Google Workspace (`google_connect`)

Connects the company's Google Workspace through its own service account, for the mailboxes the agent may act as.

Connect the company's own Google Workspace so the agent works in its Gmail, Google Calendar and Drive, which stay the source of truth. The company makes a service account in Google Cloud, and its Workspace admin gives the account's client ID domain-wide delegation for gmail.modify, calendar and drive. Give the account's JSON key and the mailboxes the agent may act as (it never acts as anyone else). Each mailbox is checked before anything is kept. On accounts with an owner, cancelling events and replacing files wait for the owner's approval by default. Free.

Price: Free. A call that fails costs nothing.

## Use it when

The company uses Gmail and Drive and wants the agent to work in them there.

## Say this to your agent

> Connect our Google Workspace for support@ only. Here is the service account's key.

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `secret` | string | yes | The service account's JSON key. Never shown again. 50 to 10,000 characters. Stored encrypted and shown only as [redacted]. |  |  |
| `mailboxes` | array of strings | yes | The addresses the agent may act as, like support@ and sales@. 1 to 20 items. |  |  |

## Example

Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon.

MCP: call `google_connect` on the MCP server `https://api.conecto.chat/mcp/googleworkspace` with these arguments:

```json
{
  "secret": "{\"type\": \"service_account\", \"client_email\": \"conecto@halverson.iam.gserviceaccount.com\", \"private_key\": \"-----BEGIN PRIVATE KEY-----...\"}",
  "mailboxes": [
    "support@halversoncycle.example"
  ]
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/google_connect \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"secret": "{\"type\": \"service_account\", \"client_email\": \"conecto@halverson.iam.gserviceaccount.com\", \"private_key\": \"-----BEGIN PRIVATE KEY-----...\"}", "mailboxes": ["support@halversoncycle.example"]}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "google_connect",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.00",
  "balance_usd": "$19.75",
  "result": {
    "google_workspace": {
      "service_account": "conecto@halverson.iam.gserviceaccount.com",
      "mailboxes": [
        "support@halversoncycle.example"
      ],
      "connected_at": "2026-10-14T08:00:00+00:00"
    },
    "need_approval": [
      "google_calendar_cancel",
      "google_drive_upload"
    ]
  }
}
```

`result`: google_workspace: service_account, mailboxes and connected_at; need_approval, the tools that now wait for the owner.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `invalid_input` | 400 | The key is not a service account key, or a mailbox is not an email address. | Send the JSON key as Google Cloud downloads it, and 1 to 20 mailboxes. |
| `vendor_rejected` | 502 | Google refused the key's delegation for a mailbox. | Give the key's client ID domain-wide delegation in the Admin console. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [google_mail_search](https://conecto.chat/tools/googleworkspace/google_mail_search.md): The newest messages in a mailbox, or those matching a Gmail search. Free up to 1,000,000 reads a month.
- [google_mail_read](https://conecto.chat/tools/googleworkspace/google_mail_read.md): One message in full, with its body as text and its attachments' names. Free up to 1,000,000 reads a month.
- [google_mail_send](https://conecto.chat/tools/googleworkspace/google_mail_send.md): Sends an email, or a reply in the same thread, as one of the company's mailboxes. $0.001 a call.
- [google_calendar_events](https://conecto.chat/tools/googleworkspace/google_calendar_events.md): The events in a mailbox's calendar between two times, in UTC. Free up to 1,000,000 reads a month.
- [google_calendar_create](https://conecto.chat/tools/googleworkspace/google_calendar_create.md): Adds an event to a mailbox's calendar and invites its attendees, with a Meet link if asked. $0.001 a call.
- [google_calendar_cancel](https://conecto.chat/tools/googleworkspace/google_calendar_cancel.md): Cancels an event and tells its attendees; waits for the owner by default. $0.001 a call.
- [google_drive_search](https://conecto.chat/tools/googleworkspace/google_drive_search.md): Files in a mailbox user's Drive, shared drives included, whose words match. Free up to 1,000,000 reads a month.
- [google_drive_read](https://conecto.chat/tools/googleworkspace/google_drive_read.md): A Drive file's words: Docs, Sheets, Slides, text, PDF or Office, up to 5 MB. Free up to 1,000,000 reads a month.
- [google_drive_upload](https://conecto.chat/tools/googleworkspace/google_drive_upload.md): Writes a text file into a Drive folder; replacing one waits for the owner. $0.001 a call.
- [google_disconnect](https://conecto.chat/tools/googleworkspace/google_disconnect.md): Forgets the service account's key and the mailboxes; nothing in Google Workspace changes. Free.