From 4165bc5eabe5b7ceccda6c6f86c9e43f6e544206 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 29 Aug 2026 15:34:32 +0000 Subject: [PATCH] guide: Google Docs --- guides/google-docs/external.md | 30 ++- guides/google-docs/meta.yaml | 60 +++--- guides/google-docs/research.md | 360 +++++++++++++++++--------------- guides/google-docs/speakeasy.md | 6 +- 4 files changed, 240 insertions(+), 216 deletions(-) diff --git a/guides/google-docs/external.md b/guides/google-docs/external.md index 4f5314f..35901aa 100644 --- a/guides/google-docs/external.md +++ b/guides/google-docs/external.md @@ -4,22 +4,20 @@ setup_version: 1 # Set up Google Docs -Sign in to the [Google Cloud console](https://console.cloud.google.com) with an account that can select a Google Cloud project, enable APIs, configure the **Google Auth platform**, and create OAuth credentials. Google does not document a Google Docs MCP-specific paid plan or license requirement. Enabling APIs requires `serviceusage.services.enable`, normally through **Service Usage Admin** or **Owner**. Obtain the approved support and contact addresses before you begin. If your organization restricts high-risk Drive & Docs scopes or unconfigured apps, you also need a Google Workspace administrator with the **Service Settings administrator** privilege. +Sign in to [console.cloud.google.com](https://console.cloud.google.com) with an account that can select a Google Cloud project, enable APIs, configure the **Google Auth platform**, and create OAuth credentials. Google does not document a Google Docs MCP-specific paid plan or license requirement. Enabling APIs requires `serviceusage.services.enable`; **Service Usage Admin** provides this permission. Each account that will connect needs **MCP Tool User** (`roles/mcp.toolUser`) on the project and access to the Google Docs it will use. Obtain the approved support and contact addresses before you begin. If your organization restricts high-risk Drive and Docs scopes or unconfigured apps, you also need a Google Workspace administrator with the **Service Settings administrator** privilege. ### Enable the Docs MCP APIs {#enable-docs-mcp-apis} 1. In the toolbar, open the resource selector. 2. Select the Google Cloud project that will own the credentials. -3. Open **APIs & Services** > **API Library**. -4. In **Search for APIs & Services**, enter `Google Docs API`. -5. Open **Google Docs API**. -6. Click **Enable**. -7. Return to **API Library**. -8. In **Search for APIs & Services**, enter `Google Docs MCP API`. -9. Open **Google Docs MCP API**. -10. Click **Enable**. +3. Open **APIs & Services** > **Library**. +4. Open **Google Docs API**. +5. Click **Enable**. +6. Return to **Library**. +7. Open **Google Docs MCP API**. +8. Click **Enable**. -If **Enable** is unavailable, ask the project owner for `serviceusage.services.enable`. +If **Enable** is unavailable, ask the project administrator for `serviceusage.services.enable`. Open **Google Auth platform** > **Branding**. @@ -35,7 +33,7 @@ If the page says **Google Auth Platform not configured yet**: 2. Under **App Information**, enter `Docs MCP Server` in **App name**. 3. Choose the approved **User support email**. 4. Click **Next**. -5. Under **Audience**, select **Internal** when every connecting user belongs to the Google Cloud project's Google Workspace organization; otherwise select **External**. +5. Under **Audience**, select **Internal** when it is available for your Google Workspace organization; otherwise select **External**. 6. Click **Next**. 7. Under **Contact Information**, enter the approved monitored address in **Email address**. 8. Click **Next**. @@ -87,8 +85,6 @@ If **Audience** is **External** and the app is in **Testing**, add every account {{ gram.oauth.callback_url }} ``` -Do not add an **Authorized JavaScript origins** value. - Prepare secure password storage before the next action. Google says the client secret in the next dialog can be copied only once. 7. Click **Create**. @@ -105,15 +101,15 @@ Keep **OAuth 2.0 client created** open. If you lost the one-time secret, delete it and create a new secret before continuing. -If your organization restricts high-risk Drive & Docs scopes or blocks unconfigured apps, continue to [Allow the OAuth client in restricted organizations](#allow-workspace-oauth-client). Otherwise, continue to [Speakeasy setup](speakeasy.md#add-server-in-speakeasy). +If your organization restricts high-risk Drive and Docs scopes or blocks unconfigured apps, continue to [Allow the OAuth client in restricted organizations](#allow-workspace-oauth-client). Otherwise, continue to [Speakeasy setup](speakeasy.md#add-server-in-speakeasy). ### Allow the OAuth client in restricted organizations {#allow-workspace-oauth-client} -Complete this step only when your organization's Workspace API controls restrict high-risk Drive & Docs scopes or block unconfigured apps. +Complete this step only when your organization's Workspace API controls restrict high-risk Drive and Docs scopes or block unconfigured apps. -1. Sign in to the [Google Admin console](https://admin.google.com) with **Service Settings administrator** access. +1. Sign in to [admin.google.com](https://admin.google.com) with **Service Settings administrator** access. 2. Open **Security** > **Access and data control** > **API controls**. 3. Click **Manage App Access**. 4. Under **Configured apps**, click **Configure new app**. @@ -124,7 +120,7 @@ Complete this step only when your organization's Workspace API controls restrict 9. Click **Continue**. 10. Choose the access approved by the security owner: - **Trusted** - - **Specific Google data**, with the four Docs MCP scopes and any required Google sign-in scopes + - **Specific Google data**, with the Docs MCP scopes and any Google sign-in scopes the app requests 11. Click **Continue**. 12. Review the settings. 13. Click **Finish**. diff --git a/guides/google-docs/meta.yaml b/guides/google-docs/meta.yaml index df262b8..d1a765b 100644 --- a/guides/google-docs/meta.yaml +++ b/guides/google-docs/meta.yaml @@ -23,7 +23,11 @@ credential_setup: - external.md#copy-client-credentials requirements: - id: google-cloud-project - description: A Google Cloud project and an administrator who can enable the Google Docs API and Google Docs MCP API, configure the Google Auth platform, and create OAuth credentials + description: A Google Cloud project that will own the Google Docs API, Google Docs MCP API, and OAuth client + - id: google-cloud-administrator + description: An administrator who can enable services, configure Google Auth platform, and create OAuth credentials; Service Usage Admin provides the service enablement permission + - id: mcp-tool-access + description: MCP Tool User on the Google Cloud project for connecting users, plus access to the Google Docs resources they will use - id: workspace-api-access description: When organizational API controls restrict high-risk Drive and Docs scopes or unconfigured apps, a Google Workspace Service Settings administrator who can allow the OAuth client documentation: @@ -33,6 +37,7 @@ remotes: - id: hosted url: https://docsmcp.googleapis.com/mcp/v1 transport: streamable-http + tenanted: false authentication: - oauth-client provenance: @@ -40,95 +45,86 @@ remotes: locator: https://developers.google.com/workspace/docs/api/guides/configure-mcp-server name: Configure the Docs MCP server classification: official - observed_at: "2026-07-29T20:37:14Z" - - source: endpoint-observation - locator: https://docsmcp.googleapis.com/mcp/v1 - name: Google Docs MCP endpoint - classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: endpoint-observation locator: https://docsmcp.googleapis.com/.well-known/oauth-protected-resource/mcp/v1 name: Google Docs MCP protected-resource metadata classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" provenance: - source: provider-documentation locator: https://developers.google.com/workspace/docs/api/guides/configure-mcp-server name: Configure the Docs MCP server classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: provider-documentation locator: https://developers.google.com/workspace/guides/configure-mcp-servers name: Configure the Google Workspace MCP servers classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: provider-documentation locator: https://developers.google.com/workspace/guides/configure-oauth-consent name: Configure the OAuth consent screen and choose scopes classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: provider-documentation locator: https://developers.google.com/workspace/guides/create-credentials name: Create access credentials classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: provider-documentation locator: https://developers.google.com/workspace/guides/enable-apis name: Enable Google Workspace APIs classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: provider-documentation locator: https://developers.google.com/workspace/docs/api/auth name: Choose Google Docs API scopes classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: provider-documentation locator: https://developers.google.com/workspace/guides/configure-mcp-security name: Configure security for Google Workspace MCP servers classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: provider-documentation locator: https://docs.cloud.google.com/mcp/set-up-authentication-mcp-servers name: Set up authentication to Google and Google Cloud MCP servers classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: provider-documentation locator: https://docs.cloud.google.com/service-usage/docs/enable-disable name: Enable and disable services classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: provider-documentation locator: https://support.google.com/a/answer/7281227?hl=en name: Control which apps access Google Workspace data classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: provider-documentation locator: https://support.google.com/cloud/answer/15549945 name: Manage App Audience classification: official - observed_at: "2026-07-29T20:37:14Z" - - source: provider-documentation - locator: https://support.google.com/cloud/answer/15549135 - name: Manage App Data Access - classification: official - observed_at: "2026-07-29T20:37:14Z" - - source: endpoint-observation - locator: https://docsmcp.googleapis.com/mcp/v1 - name: Google Docs MCP endpoint - classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: endpoint-observation locator: https://docsmcp.googleapis.com/.well-known/oauth-protected-resource/mcp/v1 name: Google Docs MCP protected-resource metadata classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: endpoint-observation locator: https://accounts.google.com/.well-known/oauth-authorization-server name: Google authorization-server metadata classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" - source: repository-doctrine locator: doctrine/speakeasy-setup.md name: Speakeasy setup canonical section classification: official - observed_at: "2026-07-29T20:37:14Z" + observed_at: "2026-08-29T15:13:21Z" + - source: pulsemcp + locator: credential-free Pulse snapshot + name: Google Docs catalog lookup + scope: public + status: no-confident-exact-match + observed_at: "2026-08-29T15:13:21Z" diff --git a/guides/google-docs/research.md b/guides/google-docs/research.md index 09d5cb4..37ad973 100644 --- a/guides/google-docs/research.md +++ b/guides/google-docs/research.md @@ -1,190 +1,204 @@ --- research_version: 1 slug: google-docs -researched_at: 2026-07-29T20:37:14Z +researched_at: 2026-08-29T15:13:21Z --- # Google Docs — Research Dossier ## Server facts -- **Remote URL**: `https://docsmcp.googleapis.com/mcp/v1`. -- **Transport**: `streamable-http`. Google calls it HTTP; a direct HTTPS - JSON-RPC `tools/list` request returned HTTP 200 JSON during this run. -- **Enablement**: enable **Google Docs API** (`docs.googleapis.com`) and - **Google Docs MCP API** (`docsmcp.googleapis.com`) in one Google Cloud - project. -- **Authentication Option**: OAuth 2.0 with a manually registered web client. - Google documents a Client ID and Client Secret and states that its remote MCP - servers do not support Dynamic Client Registration. -- **OAuth discovery**: the server publishes protected-resource metadata at +- **Remote URL:** `https://docsmcp.googleapis.com/mcp/v1`. Google publishes + one shared public endpoint; it is not region-, instance-, or + organization-specific, so the remote is not tenanted. +- **Transport:** Google labels the remote transport **HTTP**. Metadata uses the + schema's `streamable-http` value for this remote HTTP MCP endpoint. +- **Enablement:** Enable **Google Docs API** (`docs.googleapis.com`) and + **Google Docs MCP API** (`docsmcp.googleapis.com`) in the Google Cloud + project that owns the OAuth client. Enabling services requires the + `serviceusage.services.enable` permission; **Service Usage Admin** + (`roles/serviceusage.serviceUsageAdmin`) provides it. +- **Authentication Option:** OAuth 2.0 with a manually registered client. The + Speakeasy AI Control Plane is internet-hosted, so create a **Web + application** client. Google states that its remote MCP servers do not + support Dynamic Client Registration or OAuth Client ID Metadata Documents. +- **Access:** Google documents **MCP Tool User** (`roles/mcp.toolUser`) as the + role that provides `mcp.tools.call`. The connecting user also needs access to + the Docs resources they will use; the server inherits that user's permissions + and data-governance controls. +- **OAuth discovery:** Protected-resource metadata is published at `https://docsmcp.googleapis.com/.well-known/oauth-protected-resource/mcp/v1`. - It names `https://accounts.google.com/` as the authorization server. The - Speakeasy AI Control Plane can use discovered endpoints, but registration - remains manual. -- **Documented scopes**: + It names `https://accounts.google.com/` as the authorization server, so the + Control Plane can offer discovered endpoints. Client registration remains + manual. +- **Scopes required by the Docs MCP setup page:** - `https://www.googleapis.com/auth/drive.readonly` - `https://www.googleapis.com/auth/drive.file` - `https://www.googleapis.com/auth/documents.readonly` - `https://www.googleapis.com/auth/documents` -- The product-specific setup page instructs administrators to add all four - scopes. The Docs scope inventory classifies `drive.file` as non-sensitive, - the two `documents` scopes as sensitive, and `drive.readonly` as restricted. -- Live protected-resource metadata instead advertises `drive.readonly`, - `drive`, `documents.readonly`, and `documents`. The walkthrough follows the - product-specific setup page and records this conflict under Open questions. -- **Requirements and gates**: - - A Google Cloud project and an administrator who can enable APIs, configure - the Google Auth platform, and create OAuth credentials. - - Enabling APIs requires `serviceusage.services.enable`, normally through - **Service Usage Admin** or **Owner**. - - Choose **Internal** when all connecting users belong to the project's - Google Workspace organization; otherwise choose **External**. - - An External app in **Testing** permits up to 100 listed test users. Their - authorizations expire after seven days. - - Workspace API controls can block the high-risk Docs and Drive scopes. If - the organization restricts them or blocks unconfigured apps, a **Service - Settings administrator** must allow the OAuth client. -- Google warns that documents can contain indirect prompt injection and says - prompts and responses must be screened with Model Armor or an - organization-documented alternative. This is a deployment requirement, not a - technical first-connection transition. -- No Google Docs MCP-specific paid plan or license gate is documented. +- The Docs API scope inventory classifies `drive.file` as non-sensitive, both + `documents` scopes as sensitive, and `drive.readonly` as restricted. +- **Audience and testing:** Select **Internal** when available for the Google + Workspace organization; otherwise select **External**. For an External app + in **Testing**, add every account that will connect under **Test users**. + Testing permits up to 100 listed test users, and their authorizations for + these scopes expire seven days after consent. Unverified apps that present + the warning screen also have a lifetime cap of 100 new users. +- **Workspace policy gate:** Workspace API controls can restrict high-risk + scopes or block unconfigured apps. When those controls apply, a **Service + Settings administrator** must configure access for the OAuth client. +- No Google Docs MCP-specific paid plan or license requirement is stated in the + public provider documentation. +- Google requires deployments to screen prompts and responses for indirect + prompt injection with Model Armor or an organization-documented alternative. + This is a deployment safeguard rather than a first-connection console step. ## Credential flow Create one OAuth 2.0 client with **Application type** set to **Web -application**. Enter `{{ gram.oauth.callback_url }}` directly in **Authorized -redirect URIs**. +application**. Enter the callback template directly under **Authorized +redirect URIs**: + +``` +{{ gram.oauth.callback_url }} +``` | Speakeasy field | Provider origin | | --- | --- | | Client ID | **OAuth 2.0 client created** in {#copy-client-credentials} | -| Client Secret | **Client secrets** in {#copy-client-credentials}; copy immediately and store as a password | -| Scope override | The four scopes configured in {#configure-oauth-consent}, comma-separated | +| Client Secret | **Client secrets** in {#copy-client-credentials}; copy when shown and store securely | -The callback template is the same **Redirect URI** later displayed in the -Speakeasy AI Control Plane's **Attach Remote Identity Provider** sheet. Each -connecting user then authorizes with the Google Account whose Docs permissions -should apply; the server inherits that user's permissions and governance -controls. +The same callback appears later as **Redirect URI** in the Control Plane's +**Attach Remote Identity Provider** sheet. Each connecting user completes +Google's browser authorization using the account whose Docs permissions should +apply. ## Console walkthrough -Sign in at `https://console.cloud.google.com`, select the intended project, -enable both services, configure **Google Auth platform**, create and copy the -web client, conditionally allow it in Google Workspace Admin, then continue to -the Speakeasy AI Control Plane. +Sign in to the Google Cloud console, select the project that will own the OAuth +client, enable both APIs, configure **Google Auth platform**, create the client, +copy its credentials, and conditionally allow it in the Google Admin console. ### Enable the Docs MCP APIs {#enable-docs-mcp-apis} -- On the Google Cloud console toolbar, open the resource selector and select - the project that will own the OAuth client. -- Open **APIs & Services** > **API Library**. In **Search for APIs & Services**, - search for `Google Docs API`, open it, and click **Enable**. -- Return to **API Library**, search for `Google Docs MCP API`, open it, and - click **Enable**. -- If **Enable** is unavailable, ask the project owner for - `serviceusage.services.enable`. -- Next, open **Google Auth platform** > **Branding**. -- Values entered: the two API names. Values copied: none. +- Open [console.cloud.google.com](https://console.cloud.google.com). On the + toolbar, open the resource selector and select the intended project. +- Open **APIs & Services** > **Library**. Open **Google Docs API**, then click + **Enable**. +- Return to **Library**. Open **Google Docs MCP API**, then click **Enable**. +- If **Enable** is unavailable, obtain `serviceusage.services.enable` from the + project administrator before continuing. +- Continue to **Google Auth platform** > **Branding**. +- Values entered: none. Values copied: none. - Screenshot note: **Google Docs MCP API** showing its enabled state. ### Configure the OAuth consent screen {#configure-oauth-consent} -- Warning: Google says an OAuth consent screen cannot be removed after - configuration. Obtain approved support and contact addresses first. -- Open **Google Auth platform** > **Branding**. If the page says **Google Auth - Platform not configured yet**, click **Get Started**. -- In the first-time wizard: - 1. Under **App Information**, enter `Docs MCP Server` in **App name**, choose - an approved **User support email**, and click **Next**. - 2. Under **Audience**, select **Internal** when all users belong to the - project's Workspace organization; otherwise select **External**. Click - **Next**. - 3. Under **Contact Information**, enter an approved monitored **Email - address**, then click **Next**. - 4. Under **Finish**, review the Google API Services User Data Policy. With - organizational approval, select **I agree to the Google API Services: User - Data Policy**, click **Continue**, and click **Create**. -- If the platform was already configured, review **Branding**, **Audience**, - and **Data Access** instead of repeating the wizard. -- Open **Data Access**, click **Add or Remove Scopes**, and paste all four scope - URLs under **Manually add scopes**. Click **Add to Table**, **Update**, then +- Before starting, obtain approved support and contact email addresses. Google + says the OAuth consent screen cannot be removed after configuration. +- Open **Google Auth platform** > **Branding**. If **Google Auth Platform not + configured yet** appears, click **Get Started**. +- Under **App Information**, enter `Docs MCP Server` in **App name**, select an + approved **User support email**, and click **Next**. +- Under **Audience**, select **Internal**. If **Internal** is unavailable, + select **External**. Click **Next**. +- Under **Contact Information**, enter an approved monitored **Email address**, + then click **Next**. +- Under **Finish**, review the Google API Services User Data Policy. With the + organization's approval, select **I agree to the Google API Services: User + Data Policy**, click **Continue**, and click **Create**. +- If Google Auth platform was already configured, review **Branding**, + **Audience**, and **Data Access** instead of repeating the wizard. +- Open **Data Access** > **Add or Remove Scopes**. Under **Manually add + scopes**, enter the four scope URLs listed under Server facts, click **Add to + Table**, click **Update**, and then click **Save**. +- If the app is External and in **Testing**, open **Audience**. Under **Test + users**, click **Add users**, enter every account that will connect, and click **Save**. -- For an External app in **Testing**, open **Audience**. Under **Test users**, - click **Add users**, enter each connecting account, and click **Save**. -- Next, open **Google Auth platform** > **Clients**. -- Values entered: app name, support email, audience, contact email, four - scopes, and conditional test-user addresses. +- Continue to **Google Auth platform** > **Clients**. +- Values entered: app name, support email, audience, contact email, four scopes, + and conditional test-user addresses. Values copied: none. - Screenshot note: **Data Access** showing the four configured scopes. ### Create the OAuth client {#create-oauth-client} - Open **Google Auth platform** > **Clients**, then click **Create client**. -- Set **Application type** to **Web application** and enter a recognizable - **Name**, such as `Speakeasy AI Control Plane`. -- Under **Authorized redirect URIs**, click **+ Add URI** and enter - `{{ gram.oauth.callback_url }}` in **URIs**. Do not add an **Authorized - JavaScript origins** value. -- Warning: prepare secure password storage before clicking **Create**. Google - says the next dialog's client secret can be copied only once. +- Set **Application type** to **Web application**. In **Name**, enter a + recognizable name such as `Speakeasy AI Control Plane`. +- Under **Authorized redirect URIs**, click **+ Add URI**. In **URIs**, enter: + + ``` + {{ gram.oauth.callback_url }} + ``` + +- Before clicking **Create**, prepare secure storage. Google's MCP + authentication documentation says the client secret can be copied only once. - Click **Create** and keep **OAuth 2.0 client created** open. +- Values entered: client name and callback template. Values copied: none. - Screenshot note: **Create client** with **Web application** and the callback - template in **Authorized redirect URIs**. + template under **Authorized redirect URIs**. ### Copy the client credentials {#copy-client-credentials} -- Copy the **Client ID** from **OAuth 2.0 client created**. -- Under **Client secrets**, copy the **Client secret** and store it as a - password alongside the Client ID. -- If Workspace API controls restrict Docs/Drive scopes or unconfigured apps, +- Copy **Client ID** from **OAuth 2.0 client created** to secure storage. +- Under **Client secrets**, copy **Client secret** when it is shown and store it + securely beside the Client ID. +- If the one-time secret is lost during setup, delete that secret and create a + new one before continuing. +- If Workspace API controls restrict the requested data or unconfigured apps, continue to {#allow-workspace-oauth-client}. Otherwise continue to {#add-server-in-speakeasy}. -- Values copied: Client ID and Client Secret to the matching Speakeasy fields. -- Screenshot exception: do not capture a dialog containing a secret. -- Recovery: if the one-time secret is lost, delete it and create a new secret - before continuing. +- Values copied: Client ID and Client Secret for + {#connect-speakeasy-credentials}. +- Screenshot exception: do not capture a dialog that contains a secret. ### Allow the OAuth client in restricted organizations {#allow-workspace-oauth-client} -Use this step only when Workspace API controls restrict high-risk Drive & Docs -scopes or block unconfigured apps. +Use this step only when Workspace API controls restrict high-risk Drive and +Docs scopes or block unconfigured apps. -- Sign in at `https://admin.google.com` with **Service Settings administrator** - access. Open **Security** > **Access and data control** > **API controls**. +- Sign in to [admin.google.com](https://admin.google.com) with **Service + Settings administrator** access. Open **Security** > **Access and data + control** > **API controls**. - Click **Manage App Access**. Under **Configured apps**, click **Configure new app**. - Enter the Client ID from {#copy-client-credentials}, click **Search**, and select the matching app. -- Select the organizational units whose users will connect and click +- Select the organizational units whose users will connect, then click **Continue**. - Choose the access approved by the security owner: **Trusted**, or **Specific - Google data** with the four Docs MCP scopes and any required Google sign-in - scopes. + Google data** with the Docs MCP scopes and any Google sign-in scopes the app + requests. - Click **Continue**, review the settings, and click **Finish**. Google says changes can take up to 24 hours, though they usually apply sooner. - Continue to {#add-server-in-speakeasy}. +- Values entered: Client ID, organizational units, and approved access level. + Values copied: none. - Screenshot note: the access review with the Client ID redacted. ## Speakeasy setup Transcluded from `doctrine/speakeasy-setup.md`, observed at -`2026-07-29T20:37:14Z`. Its fixed anchors are carried verbatim. +`2026-08-29T15:13:21Z`. Its fixed anchors are carried verbatim. -The Speakeasy MCP Catalog lookup was **absent** for `google-docs` and -`google docs`. Render only the Custom remote server path. +The credential-free Pulse snapshot observed at `2026-08-29T15:13:21Z` had no +confident exact Google Docs MCP catalog match. Preserve +`speakeasy_add_server: custom-remote` and render only the Custom remote path. ### Add the server in Speakeasy {#add-server-in-speakeasy} In the Speakeasy AI Control Plane sidebar, under **Connect**, select **Sources**, then click **Add Source**. -Choose **Custom remote server**. On **Add a custom remote MCP server**, paste -`https://docsmcp.googleapis.com/mcp/v1` into **Remote MCP server URL** and click -**Add server**. +Choose **Custom remote server**. On the **Add a custom remote MCP server** +page, paste this value into **Remote MCP server URL**: -This creates the hosted MCP server and opens its **Overview** page. +``` +https://docsmcp.googleapis.com/mcp/v1 +``` + +Click **Add server**. This creates the hosted MCP server and opens its +**Overview** page. @@ -193,25 +207,26 @@ Per-guide values: - Remote URL: `https://docsmcp.googleapis.com/mcp/v1` - Transport: `streamable-http`; **Transport** is read-only. - Authentication Option: `oauth-client`, manual OAuth. +- Required provider scopes: the four scope URLs listed under Server facts. ### Connect your credentials {#connect-speakeasy-credentials} -From **Overview**, open **Settings**. Under **Authentication**, click -**Configure Manually**, or **Use Discovered** when offered. In **Attach Remote -Identity Provider**, set **Client Type** to **Manual**. - -Confirm **Redirect URI** matches the callback registered in -{#create-oauth-client}. Paste the **Client ID** and **Client Secret (optional)** -from {#copy-client-credentials}; Google requires its generated secret. +From the server's **Overview**, open **Settings**. Under **Authentication**, +click **Configure Manually**, or click **Use Discovered** when offered because +the provider publishes protected-resource and authorization-server metadata. -In **Scope (override)**, enter: -`https://www.googleapis.com/auth/drive.readonly, https://www.googleapis.com/auth/drive.file, https://www.googleapis.com/auth/documents.readonly, https://www.googleapis.com/auth/documents`. -Click **Attach Identity Provider**. +In the **Attach Remote Identity Provider** sheet, set **Client Type** to +**Manual**. Paste **Client ID** and **Client Secret (optional)** from +{#copy-client-credentials}, then click **Attach Identity Provider**. Google +requires the generated client secret for this MCP client path. Confirm that the +sheet's **Redirect URI** matches the callback registered in +{#create-oauth-client}. -Complete Google's browser authorization with the intended account. An External -app in **Testing** requires that account under **Test users**. +When a client first needs access, complete Google's browser authorization with +the intended account. If the app is External and in **Testing**, that account +must be listed under **Test users**. -Screenshot note: the manual identity-provider sheet with credentials redacted. + Further-reading URL: `https://developers.google.com/workspace/docs/api/guides/configure-mcp-server`. @@ -220,53 +235,70 @@ This guide covers setup only. For anything beyond it — billing, tool behavior, limits — see Google's Docs MCP documentation at https://developers.google.com/workspace/docs/api/guides/configure-mcp-server. -## Open questions - -- Google's Docs MCP setup page requires `drive.file`, while live - protected-resource metadata advertises broad `drive` instead and omits - `drive.file`. The guide follows the explicit setup page; confirm which source - Google intends to update. +## Research limitations + +- The product-specific setup page requires `drive.file`, while live + protected-resource metadata advertises broad `drive` and omits `drive.file`. + The guide follows the explicit Docs MCP setup page because it is the + task-specific provider instruction. This is safely hedgeable and not an + operator decision. +- Google's MCP authentication page requires copying a client secret for a web + client, while the generic Workspace credentials page says web applications do + not use client secrets. The guide follows the MCP-specific sources. +- Google calls the transport HTTP but does not name the MCP transport revision + on the product page. The metadata value uses the schema-supported + `streamable-http` normalization for the remote HTTP MCP endpoint. +- Exa could read the public OAuth metadata but could not perform a fresh POST + handshake against the MCP endpoint. The provider's current product page is + therefore the source for the endpoint and transport facts. +- The provider documentation does not state a Google Docs MCP-specific paid + plan or license gate. `https://developers.google.com/llms.txt` was not + available during the documentation sweep. + +## Operator decisions + +None. ## Provenance -Source inventory: Google Workspace developer documentation +Source inventory from the sweep: Google Workspace developer documentation (`developers.google.com`, drawn from); Google Cloud documentation (`docs.cloud.google.com`, drawn from); Google Workspace Admin Help -(`support.google.com/a`, drawn from); Google Cloud Console Help +(`support.google.com/a`, drawn from); Google Auth Platform Help (`support.google.com/cloud`, drawn from); Google Codelabs -(`codelabs.developers.google.com`, swept but not drawn from). -`https://developers.google.com/llms.txt` returned 404. +(`codelabs.developers.google.com`, swept but not drawn from). The +`developers.google.com` machine-readable index was unavailable. -All sources were observed at `2026-07-29T20:37:14Z`: +All sources below were observed at `2026-08-29T15:13:21Z`: - `https://developers.google.com/workspace/docs/api/guides/configure-mcp-server` - — endpoint, HTTP transport, APIs, scopes, consent, client credentials, and - security warning. + — endpoint, HTTP transport, API enablement, OAuth flow, four scopes, audience, + client registration, and security warning. - `https://developers.google.com/workspace/guides/configure-mcp-servers` — - corroborating Workspace MCP endpoint, APIs, scopes, and OAuth flow. + corroborating Workspace MCP endpoint, services, scopes, and OAuth labels. - `https://developers.google.com/workspace/guides/configure-oauth-consent` — - consent wizard, audience, scopes, and test users. -- `https://developers.google.com/workspace/guides/create-credentials` — - web-client controls and redirect URI. + consent configuration, audience, data access, and test users. +- `https://developers.google.com/workspace/guides/create-credentials` — generic + Workspace OAuth client labels and the documented client-secret conflict. - `https://developers.google.com/workspace/guides/enable-apis` — API Library - and Docs API enablement. -- `https://developers.google.com/workspace/docs/api/auth` — scope descriptions - and classifications. + navigation and enablement labels. +- `https://developers.google.com/workspace/docs/api/auth` — scope meanings and + sensitivity classifications. - `https://developers.google.com/workspace/guides/configure-mcp-security` — - prompt-injection screening requirement. -- `https://docs.cloud.google.com/mcp/set-up-authentication-mcp-servers` — - manual registration, one-time secret, and OAuth configuration. -- `https://docs.cloud.google.com/service-usage/docs/enable-disable` — API - enablement labels and permission requirement. -- `https://support.google.com/a/answer/7281227?hl=en` — Workspace API controls, - high-risk scopes, and app access. -- `https://support.google.com/cloud/answer/15549945` — Audience testing limits - and expiry. -- `https://support.google.com/cloud/answer/15549135` — Data Access controls. -- `https://docsmcp.googleapis.com/mcp/v1` — direct JSON-RPC transport - observation. + indirect prompt-injection safeguards. +- `https://docs.cloud.google.com/mcp/set-up-authentication-mcp-servers` — DCR + limitation, required MCP role, web-client flow, callback requirement, and + one-time client secret. +- `https://docs.cloud.google.com/service-usage/docs/enable-disable` — Service + Usage Admin role and service enablement. +- `https://support.google.com/a/answer/7281227?hl=en` — Service Settings + administrator privilege, API controls, and app access levels. +- `https://support.google.com/cloud/answer/15549945` — External testing, + seven-day authorization expiry, and user cap. - `https://docsmcp.googleapis.com/.well-known/oauth-protected-resource/mcp/v1` - — live protected-resource metadata. -- `https://accounts.google.com/.well-known/oauth-authorization-server` — live - authorization-server metadata. -- `doctrine/speakeasy-setup.md` — Speakeasy labels and fixed anchors. + — resource URL, authorization server, bearer method, and advertised scopes. +- `https://accounts.google.com/.well-known/oauth-authorization-server` — + authorization and token endpoints; no dynamic registration endpoint. +- `doctrine/speakeasy-setup.md` — Control Plane labels and fixed anchors. +- Credential-free Pulse snapshot — no confident exact Google Docs MCP catalog + match; safe Custom remote override retained. diff --git a/guides/google-docs/speakeasy.md b/guides/google-docs/speakeasy.md index 049ece6..2b5988a 100644 --- a/guides/google-docs/speakeasy.md +++ b/guides/google-docs/speakeasy.md @@ -24,7 +24,7 @@ This creates the hosted MCP server and opens its **Overview** page. The **Transp 3. In **Attach Remote Identity Provider**, set **Client Type** to **Manual**. 4. Confirm that **Redirect URI** matches `{{ gram.oauth.callback_url }}`, which you entered when you [created the OAuth client](external.md#create-oauth-client). 5. In **Client ID**, paste the value you [copied from Google](external.md#copy-client-credentials). -6. In **Client Secret (optional)**, paste the secret you copied from Google. Google requires this value. +6. In **Client Secret (optional)**, paste the secret you [copied from Google](external.md#copy-client-credentials). Google requires this value. 7. In **Scope (override)**, enter this value: ``` @@ -33,8 +33,8 @@ This creates the hosted MCP server and opens its **Overview** page. The **Transp 8. Click **Attach Identity Provider**. -Complete Google's browser authorization with the intended Google Account. If the app is **External** and in **Testing**, that account must be under **Test users**. +Complete Google's browser authorization with the intended account. If the app is **External** and in **Testing**, that account must be listed under **Test users**. - + This guide covers setup only. For anything beyond it — billing, tool behavior, limits — see [Google's Docs MCP documentation](https://developers.google.com/workspace/docs/api/guides/configure-mcp-server).