speakeasy-api · walker-tx · Aug 20, 2026 · Aug 20, 2026
diff --git a/guides/gmail/external.md b/guides/gmail/external.md
@@ -0,0 +1,100 @@
+---
+setup_version: 1
+---
+
+# Gmail setup
+
+You need a Google Workspace account enrolled in the Google Workspace Developer Preview Program and a Google Cloud project registered through that program. If you do not already have a project, ask your organization's Google Cloud administrator for an existing project, its project number, and permission to enable services. Open the [Google Workspace Developer Preview Program page](https://developers.google.com/workspace/preview), submit its enrollment form with your Google Workspace account and the Google Cloud project number, and wait for Google to verify the account, add you to the program Google Group, and register the project before continuing. In the project, you need permission to enable services, such as the **Service Usage Admin** role; a project creator already has the required permission. Sign in at [console.cloud.google.com](https://console.cloud.google.com/) and select the registered project in the resource selector.
+
+### Enable the Gmail API {#enable-gmail-api}
+
+1. Open **APIs & Services** > **API Library**.
+2. Confirm that the registered project is selected in the resource selector.
+3. In **Search for APIs & Services**, enter `Gmail API`.
+4. Select **Gmail API**.
+5. Click **Enable**.
+
+<!-- screenshot: the Gmail API detail page with the selected project visible and Enable ready to click -->
+
+### Enable the Gmail MCP API {#enable-gmail-mcp-api}
+
+1. Return to **APIs & Services** > **API Library**.
+2. In **Search for APIs & Services**, enter `Gmail MCP API`.
+3. Select **Gmail MCP API**.
+4. Click **Enable**.
+
+If the service is unavailable, confirm that the selected project is the project registered through the Google Workspace Developer Preview Program.
+
+<!-- screenshot: the Gmail MCP API detail page with Enable and the selected project visible -->
+
+### Configure the OAuth consent screen {#configure-oauth-consent}
+
+1. Open **Google Auth Platform** > **Branding**.
+2. If **Google Auth Platform not configured yet** appears, click **Get Started**.
+3. Under **App Information**, enter `Gmail MCP Server` in **App name**.
+4. In **User support email**, choose your email address or an appropriate Google group.
+5. Click **Next**.
+6. Under **Audience**, choose **Internal**. If **Internal** is unavailable, choose **External**.
+7. Click **Next**.
+8. Under **Contact Information**, enter an **Email address** for project notifications.
+9. Click **Next**.
+10. Under **Finish**, review the Google API Services User Data Policy.
+11. If you accept the policy, select **I agree to the Google API Services: User Data Policy**.
+12. Click **Continue**.
+13. Click **Create**. This returns you to the configured Google Auth Platform.
+14. If you selected **External**, open **Audience**.
+15. Under **Test users**, click **Add users**.
+16. Enter the email addresses that will authorize the first connection.
+17. Click **Save**.
+18. Open **Data Access**.
+19. Click **Add or Remove Scopes**.
+20. Under **Manually add scopes**, paste these scopes:
+
+```text
+https://www.googleapis.com/auth/gmail.readonly
+https://www.googleapis.com/auth/gmail.compose
+```
+
+21. Click **Add to Table**.
+22. Click **Update** to return to **Data Access**.
+23. Click **Save**.
+
+If Google Auth Platform is already configured, retain your organization's approved branding and audience. Use **Audience** to add test users when applicable, then use **Data Access** to add the required scopes.
+
+<!-- screenshot: the Data Access scope panel with the two Gmail scope rows selected and user email addresses excluded -->
+
+### Create the OAuth client {#create-oauth-client}
+
+1. From Google Auth Platform, open **Clients**.
+2. Click **Create Client**.
+3. Set **Application type** to **Web application**.
+4. Enter an organization-approved **Name**, such as `Speakeasy Gmail MCP`.
+5. Under **Authorized redirect URIs**, click **+ Add URI**.
+6. Enter:
+
+```text
+{{ gram.oauth.callback_url }}
+```
+
+Before you click **Create**, prepare to save the secret in an approved secret manager. Google shows and permits downloading the full client secret only at creation.
+
+7. Click **Create**.
+8. Copy the **Client ID** for the [Speakeasy setup](speakeasy.md#connect-speakeasy-credentials).
+9. Copy the **Client Secret** for the [Speakeasy setup](speakeasy.md#connect-speakeasy-credentials), and store it securely before closing the creation result.
+
+If you closed the creation result without saving the full secret:
+
+1. Reopen **Google Auth Platform** > **Clients**.
+2. Confirm that the same project is selected.
+3. Under **OAuth 2.0 Client IDs**, click the client you created.
+4. Under **Client secrets**, find the missed secret.
+5. Click **Disable**.
+6. Click the delete button next to the disabled secret.
+
+Prepare the approved secret manager before the next action. The new secret is visible only when it is created.
+
+7. Click **Add Secret**.
+8. Immediately copy the new secret to the approved secret manager.
+9. Use the new value in Speakeasy.
+
+<!-- screenshot: the client form showing Web application and the Authorized redirect URIs row, with organization-specific values redacted -->
diff --git a/guides/gmail/meta.yaml b/guides/gmail/meta.yaml
@@ -0,0 +1,77 @@
+# yaml-language-server: $schema=../../schema/guide.v1.schema.json
+schema_version: 1
+slug: gmail
+title: Gmail
+summary: Connect the Gmail remote MCP server with a Google Cloud OAuth client.
+speakeasy_add_server: custom-remote
+credential_setup:
+  requirements:
+    - id: developer-preview
+      description: Membership in the Google Workspace Developer Preview Program with the Google Cloud project registered for preview access.
+    - id: google-cloud-project
+      description: A Google Cloud project with permission to enable services, such as the Service Usage Admin role.
+  options:
+    - id: gmail-oauth
+      kind: oauth
+      client_registration: manual
+      upstream_setup: provider-steps
+      fields:
+        - id: client-id
+          label: Client ID
+          setup:
+            - external.md#create-oauth-client
+        - id: client-secret
+          label: Client Secret
+          setup:
+            - external.md#create-oauth-client
+remotes:
+  - id: gmail
+    url: https://gmailmcp.googleapis.com/mcp/v1
+    transport: streamable-http
+    authentication:
+      - gmail-oauth
+    provenance:
+      - source: google-developers
+        locator: https://developers.google.com/workspace/gmail/api/guides/configure-mcp-server
+        classification: official
+        observed_at: "2026-08-20T19:49:41Z"
+      - source: google-developers
+        locator: https://developers.google.com/workspace/gmail/api/reference/mcp
+        classification: official
+        observed_at: "2026-08-20T19:49:41Z"
+documentation:
+  external: external.md
+  speakeasy: speakeasy.md
+provenance:
+  - source: google-developers
+    locator: https://developers.google.com/workspace/gmail/api/guides/configure-mcp-server
+    classification: official
+    observed_at: "2026-08-20T19:49:41Z"
+  - source: google-developers
+    locator: https://developers.google.com/workspace/gmail/api/reference/mcp
+    classification: official
+    observed_at: "2026-08-20T19:49:41Z"
+  - source: google-developers
+    locator: https://developers.google.com/workspace/preview
+    classification: official
+    observed_at: "2026-08-20T19:49:41Z"
+  - source: google-cloud-console
+    locator: https://console.cloud.google.com/
+    classification: official
+    observed_at: "2026-08-20T19:49:41Z"
+  - source: google-cloud-docs
+    locator: https://docs.cloud.google.com/mcp/authenticate-mcp
+    classification: official
+    observed_at: "2026-08-20T19:49:41Z"
+  - source: google-cloud-docs
+    locator: https://docs.cloud.google.com/service-usage/docs/enable-disable
+    classification: official
+    observed_at: "2026-08-20T19:49:41Z"
+  - source: google-cloud-support
+    locator: https://support.google.com/cloud/answer/15549257?hl=en
+    classification: official
+    observed_at: "2026-08-20T19:49:41Z"
+  - source: speakeasy-doctrine
+    locator: doctrine/speakeasy-setup.md
+    classification: official
+    observed_at: "2026-08-20T19:49:41Z"
diff --git a/guides/gmail/pipeline.lock.json b/guides/gmail/pipeline.lock.json
@@ -0,0 +1,217 @@
+{
+  "schema_version": 1,
+  "slug": "gmail",
+  "persona": "it-admin",
+  "runtime": "pi",
+  "updated_at": "2026-08-20T19:57:49Z",
+  "steps": {
+    "research": {
+      "input_digest": "sha256:e9253583138a4e06096eee9d53a998d08c49990a34ae72b752879cb19de08ef7",
+      "inputs": {
+        "model": "openrouter/openai/gpt-5.6-sol",
+        "prompt_digest": "sha256:255c60266361ff6711b0b04829329485020218f5a0460f70aa30f30d9c1711fc",
+        "reading_list": [
+          {
+            "path": "doctrine/glossary.md",
+            "digest": "sha256:8d14a903b777a43a7e73f2612be0846195143f9a37ebf5b60815a49d28acbd8f"
+          },
+          {
+            "path": "doctrine/shared.md",
+            "digest": "sha256:7da98efa7ef9b5772be6346d54d6bd4fd230d0a2d62786016f7ee8265ff1b8db"
+          },
+          {
+            "path": "doctrine/roles/technical-research.md",
+            "digest": "sha256:88f093f873c705128a0a31eb38be298a2ee11f4d50815552739925337f8ac3ad"
+          },
+          {
+            "path": "doctrine/speakeasy-setup.md",
+            "digest": "sha256:9f173facc7f63e450eb7e4d693c67c0a88e9ff68f0a381cfcbae413a8d47dd16"
+          }
+        ],
+        "artifacts": [],
+        "params": {
+          "provider": "gmail",
+          "notes": "MCP server endpoint: https://gmailmcp.googleapis.com/mcp/v1\n\nSpeakeasy MCP Catalog: absent"
+        }
+      },
+      "outputs": [
+        {
+          "path": "research.md",
+          "digest": "sha256:913cf54b74a9a55f9cae985b1184387b946edb19dfa32a75443828c81f145a8b"
+        },
+        {
+          "path": "meta.yaml",
+          "digest": "sha256:b8407ec66741ecb6bea863b061a288f359405be9190e234e360497906cce1d7e"
+        }
+      ],
+      "completed_at": "2026-08-20T19:57:49Z"
+    },
+    "draft": {
+      "input_digest": "sha256:d3cf9ee59216350d497bfe8329df08fa57097bc22132d6353c52ae99df6258d1",
+      "inputs": {
+        "model": "openrouter/openai/gpt-5.6-sol",
+        "prompt_digest": "sha256:ad649d12e8bf3882a1593555c0c4d31681ac50aa891177b1a8f766a563d85d6c",
+        "reading_list": [
+          {
+            "path": "doctrine/glossary.md",
+            "digest": "sha256:8d14a903b777a43a7e73f2612be0846195143f9a37ebf5b60815a49d28acbd8f"
+          },
+          {
+            "path": "doctrine/shared.md",
+            "digest": "sha256:7da98efa7ef9b5772be6346d54d6bd4fd230d0a2d62786016f7ee8265ff1b8db"
+          },
+          {
+            "path": "doctrine/roles/writer.md",
+            "digest": "sha256:4214af68feea7dfc68fab1058e1d5d35e6238d5b51fd9b10db421ebafc49a3cc"
+          },
+          {
+            "path": "doctrine/personas/it-admin.md",
+            "digest": "sha256:38c1356b43c9e5f92527f9b73e8561a62cb2eb636b675796af49d0b6015dd9be"
+          }
+        ],
+        "artifacts": [
+          {
+            "path": "research.md",
+            "digest": "sha256:913cf54b74a9a55f9cae985b1184387b946edb19dfa32a75443828c81f145a8b"
+          },
+          {
+            "path": "meta.yaml",
+            "digest": "sha256:b8407ec66741ecb6bea863b061a288f359405be9190e234e360497906cce1d7e"
+          }
+        ],
+        "params": {
+          "provider": "gmail",
+          "notes": "MCP server endpoint: https://gmailmcp.googleapis.com/mcp/v1\n\nSpeakeasy MCP Catalog: overridden-custom-remote",
+          "persona": "it-admin"
+        }
+      },
+      "outputs": [
+        {
+          "path": "external.md",
+          "digest": "sha256:2b2df82fbb00977cbd3263d54dd5c0e0f4a9d1d649163c742565c6fbd1ba4b78"
+        },
+        {
+          "path": "speakeasy.md",
+          "digest": "sha256:6946216638aca0a4fab541b56ca6e99f3c78baa31e14d3943e97ef7a2ae134a8"
+        }
+      ],
+      "completed_at": "2026-08-20T19:57:49Z"
+    },
+    "review.fidelity": {
+      "input_digest": "sha256:53a2862f5bdc703e7215ef27d9b1c41cf6fd4fd9784d64d144d4e5be7b85a031",
+      "inputs": {
+        "model": "openrouter/openai/gpt-5.6-sol",
+        "prompt_digest": "sha256:2885ba720bba92fbed782f1ac13fdbd065c3f1a294302ee85792fc4f61866e1f",
+        "reading_list": [
+          {
+            "path": "doctrine/glossary.md",
+            "digest": "sha256:8d14a903b777a43a7e73f2612be0846195143f9a37ebf5b60815a49d28acbd8f"
+          },
+          {
+            "path": "doctrine/shared.md",
+            "digest": "sha256:7da98efa7ef9b5772be6346d54d6bd4fd230d0a2d62786016f7ee8265ff1b8db"
+          },
+          {
+            "path": "doctrine/roles/fidelity.md",
+            "digest": "sha256:f1c64906d2702d25c5db118f0a1a471b4962333a506c235ffebccf67413aa7f3"
+          }
+        ],
+        "artifacts": [
+          {
+            "path": "research.md",
+            "digest": "sha256:913cf54b74a9a55f9cae985b1184387b946edb19dfa32a75443828c81f145a8b"
+          },
+          {
+            "path": "meta.yaml",
+            "digest": "sha256:b8407ec66741ecb6bea863b061a288f359405be9190e234e360497906cce1d7e"
+          },
+          {
+            "path": "external.md",
+            "digest": "sha256:2b2df82fbb00977cbd3263d54dd5c0e0f4a9d1d649163c742565c6fbd1ba4b78"
+          },
+          {
+            "path": "speakeasy.md",
+            "digest": "sha256:6946216638aca0a4fab541b56ca6e99f3c78baa31e14d3943e97ef7a2ae134a8"
+          }
+        ],
+        "params": {
+          "provider": "gmail",
+          "notes": "MCP server endpoint: https://gmailmcp.googleapis.com/mcp/v1\n\nSpeakeasy MCP Catalog: overridden-custom-remote",
+          "persona": "it-admin",
+          "dimension": "fidelity"
+        }
+      },
+      "outputs": [
+        {
+          "path": "external.md",
+          "digest": "sha256:2b2df82fbb00977cbd3263d54dd5c0e0f4a9d1d649163c742565c6fbd1ba4b78"
+        },
+        {
+          "path": "speakeasy.md",
+          "digest": "sha256:6946216638aca0a4fab541b56ca6e99f3c78baa31e14d3943e97ef7a2ae134a8"
+        }
+      ],
+      "completed_at": "2026-08-20T19:57:49Z"
+    },
+    "review.achievability": {
+      "input_digest": "sha256:9df3bf3b400e9268fa2f73d6967f2ce5d7ea26704997e0199510ccd69f32b679",
+      "inputs": {
+        "model": "openrouter/openai/gpt-5.6-sol",
+        "prompt_digest": "sha256:0b287f892ece7611416030973e4b1952db4c173e3023930bf238685d39b79cdf",
+        "reading_list": [
+          {
+            "path": "doctrine/glossary.md",
+            "digest": "sha256:8d14a903b777a43a7e73f2612be0846195143f9a37ebf5b60815a49d28acbd8f"
+          },
+          {
+            "path": "doctrine/shared.md",
+            "digest": "sha256:7da98efa7ef9b5772be6346d54d6bd4fd230d0a2d62786016f7ee8265ff1b8db"
+          },
+          {
+            "path": "doctrine/roles/review.md",
+            "digest": "sha256:7eb1e560946bbc2656afdfbdbd26d85b3d4a5579818fc4bd6629d818ce251f69"
+          },
+          {
+            "path": "doctrine/personas/it-admin.md",
+            "digest": "sha256:38c1356b43c9e5f92527f9b73e8561a62cb2eb636b675796af49d0b6015dd9be"
+          }
+        ],
+        "artifacts": [
+          {
+            "path": "research.md",
+            "digest": "sha256:913cf54b74a9a55f9cae985b1184387b946edb19dfa32a75443828c81f145a8b"
+          },
+          {
+            "path": "meta.yaml",
+            "digest": "sha256:b8407ec66741ecb6bea863b061a288f359405be9190e234e360497906cce1d7e"
+          },
+          {
+            "path": "external.md",
+            "digest": "sha256:2b2df82fbb00977cbd3263d54dd5c0e0f4a9d1d649163c742565c6fbd1ba4b78"
+          },
+          {
+            "path": "speakeasy.md",
+            "digest": "sha256:6946216638aca0a4fab541b56ca6e99f3c78baa31e14d3943e97ef7a2ae134a8"
+          }
+        ],
+        "params": {
+          "provider": "gmail",
+          "notes": "MCP server endpoint: https://gmailmcp.googleapis.com/mcp/v1\n\nSpeakeasy MCP Catalog: overridden-custom-remote",
+          "persona": "it-admin",
+          "dimension": "achievability"
+        }
+      },
+      "outputs": [
+        {
+          "path": "external.md",
+          "digest": "sha256:2b2df82fbb00977cbd3263d54dd5c0e0f4a9d1d649163c742565c6fbd1ba4b78"
+        },
+        {
+          "path": "speakeasy.md",
+          "digest": "sha256:6946216638aca0a4fab541b56ca6e99f3c78baa31e14d3943e97ef7a2ae134a8"
+        }
+      ],
+      "completed_at": "2026-08-20T19:57:49Z"
+    }
+  }
+}