mcp-google-workspace

Overview Schema Source Related Servers Discussions Admin

Connect Google Workspace

connect_google_workspace

Connects a Google account or adds Workspace services to an existing connection so Gmail, Calendar, Drive, and other tools can run; returns local connection state or a remote authorization URL.

Instructions

Connect the user's Google account, or add services to an existing connection, so Workspace tools can run. In local mode (no remote OAuth callback configured) it runs Google's browser consent flow on the server machine and waits up to 180 seconds by default, unless the stored grant already covers every enabled service. In remote mode it returns a one-time authorization_url, valid for 10 minutes, for the user to open. Returns state, connected and granted_capabilities locally, or authorization_url, expires_at and requested_scopes remotely; after remote consent call get_google_connection_status.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "connect_google_workspace"
  }
}

Input Schema

Name	Required	Description	Default
`capabilities`	No	Services to request access for; omit for ['gmail']. In remote mode these scopes are added to the ones already granted; in local mode the names are only validated and every enabled service is requested.

Output Schema

Name	Required	Description	Default
`mode`	No
`state`	No
`action`	No
`connected`	No
`expires_at`	No
`capabilities`	No
`after_consent`	No
`granted_scopes`	No
`requested_scopes`	No
`authorization_url`	No
`granted_capabilities`	No
`newly_requested_scopes`	No
`requested_capabilities`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed34 schema fields changedv2.1.0Nov 6, 2026

removedInput schema / maxProperties
```
Removed value: -10000
```

removedInput schema / properties / capabilities / anyOf

Removed value: -[
-  {
-    "items": {
-      "maxLength": 1000000,
-      "type": "string"
-    },
-    "maxItems": 10000,
-    "type": "array"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / capabilities / default
```
Removed value: -null
```

changedInput schema / properties / capabilities / description

Previous value: -"Google Workspace capability names to request scopes for, e.g. ['calendar', 'chat', 'docs', 'drive', 'forms', 'gmail', 'keep', 'meet', 'people', 'sheets', 'slides', 'tasks']; defaults to ['gmail'] when omitted."New value: +"Services to request access for; omit for ['gmail']. In remote mode these scopes are added to the ones already granted; in local mode the names are only validated and every enabled service is requested."

addedInput schema / properties / capabilities / items

Added value: +{
+  "enum": [
+    "calendar",
+    "chat",
+    "docs",
+    "drive",
+    "forms",
+    "gmail",
+    "keep",
+    "meet",
+    "people",
+    "sheets",
+    "slides",
+    "tasks"
+  ],
+  "type": "string"
+}

addedInput schema / properties / capabilities / type
```
Added value: +"array"
```
changedOutput schema / additionalProperties
```
Previous value: -falseNew value: +true
```

removedOutput schema / description

Removed value: -"Structured response returned by this MCP tool."

removedOutput schema / properties / action / description
```
Removed value: -"Response field: action."
```
changedOutput schema / properties / after_consent / additionalProperties
```
Previous value: -falseNew value: +true
```
removedOutput schema / properties / after_consent / description
```
Removed value: -"Response field: after consent."
```
removedOutput schema / properties / after_consent / properties / arguments / description
```
Removed value: -"Response field: arguments."
```
removedOutput schema / properties / after_consent / properties / tool / description
```
Removed value: -"Response field: tool."
```
removedOutput schema / properties / authorization_url / description
```
Removed value: -"Response field: authorization url."
```
removedOutput schema / properties / capabilities / description
```
Removed value: -"Response field: capabilities."
```
removedOutput schema / properties / capabilities / items
```
Removed value: -{}
```
removedOutput schema / properties / capabilities / type
```
Removed value: -"array"
```
removedOutput schema / properties / connected / description
```
Removed value: -"Response field: connected."
```
removedOutput schema / properties / expires_at / description
```
Removed value: -"Response field: expires at."
```
removedOutput schema / properties / granted_capabilities / description
```
Removed value: -"Response field: granted capabilities."
```
removedOutput schema / properties / granted_capabilities / items
```
Removed value: -{}
```
removedOutput schema / properties / granted_capabilities / type
```
Removed value: -"array"
```
removedOutput schema / properties / granted_scopes / description
```
Removed value: -"Response field: granted scopes."
```
removedOutput schema / properties / granted_scopes / items
```
Removed value: -{}
```
removedOutput schema / properties / granted_scopes / type
```
Removed value: -"array"
```
removedOutput schema / properties / mode / description
```
Removed value: -"Response field: mode."
```
removedOutput schema / properties / newly_requested_scopes / description
```
Removed value: -"Response field: newly requested scopes."
```
removedOutput schema / properties / requested_capabilities / description
```
Removed value: -"Response field: requested capabilities."
```
removedOutput schema / properties / requested_capabilities / items
```
Removed value: -{}
```
removedOutput schema / properties / requested_capabilities / type
```
Removed value: -"array"
```
removedOutput schema / properties / requested_scopes / description
```
Removed value: -"Response field: requested scopes."
```

removedOutput schema / properties / resource

Removed value: -{
-  "additionalProperties": false,
-  "description": "Stable cross-tool Workspace resource handle when applicable.",
-  "properties": {
-    "etag": {
-      "description": "Provider entity tag.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "id": {
-      "description": "Provider resource identifier.",
-      "type": "string"
-    },
-    "kind": {
-      "description": "Workspace resource kind.",
-      "type": "string"
-    },
-    "mime_type": {
-      "description": "MIME type when applicable.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "modified_at": {
-      "description": "Last modification time.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "name": {
-      "description": "Human-readable name.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "uri": {
-      "description": "Stable Workspace resource URI.",
-      "type": "string"
-    },
-    "web_url": {
-      "description": "Provider web URL.",
-      "type": [
-        "string",
-        "null"
-      ]
-    }
-  },
-  "required": [
-    "kind",
-    "id",
-    "uri"
-  ],
-  "type": "object"
-}

removedOutput schema / properties / state / description
```
Removed value: -"Response field: state."
```

removedOutput schema / title

Removed value: -"Connect Google Workspace response"

First observedv0.3.7Jul 29, 2026

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond the annotations: a blocking browser consent flow with a 180-second default wait in local mode, a one-time authorization_url valid for 10 minutes in remote mode, and the short-circuit when grants already exist. These are exactly the operational traits an agent needs and none are derivable from readOnlyHint/openWorldHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded and the mode split is logically ordered, with no filler. The enumeration of return fields (state, connected, granted_capabilities, authorization_url, expires_at, requested_scopes) partly duplicates the existing output schema, which is the only wasted clause.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an OAuth connection tool with side effects this covers both execution modes, timing/expiry limits, the no-op path, and the follow-up call. Return values are covered by the output schema, so nothing an agent needs is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the capabilities property already documents the default ['gmail'] and the mode-dependent scoping rules. The description reinforces the mode distinction but adds no syntax or semantics the schema lacks, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Connect the user's Google account, or add services to an existing connection') plus the downstream payoff ('so Workspace tools can run'), which clearly separates it from disconnect_google_workspace and get_google_connection_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing: remote mode returns an authorization_url and the agent must then call get_google_connection_status. It also explains the no-op case (stored grant already covers enabled services). It does not say whether to check connection status before calling, so not quite a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server