How to set up the Gmail MCP server

Gmail MCP lets a compatible client work with mail that the authorized Google Workspace user can access. It uses Google OAuth 2.0 only, after the Workspace Developer Preview and required Google APIs are enabled.

This guide covers the Google-side preparation for Gmail's remote MCP server. It applies to any compatible MCP client. The Gmail agent template is a separate deployment step; it does not create the Google Cloud project or OAuth approval below.

Google Workspace MCP servers are in the Google Workspace Developer Preview Program. Gmail is a separate remote server with the Streamable HTTP endpoint https://gmailmcp.googleapis.com/mcp/v1 and OAuth 2.0 authentication.

Choose a connection method

Google Workspace MCP supports Google OAuth 2.0 for Gmail; it does not offer a bearer-token alternative for this server. The Google Workspace MCP configuration guide is the source of truth for the endpoint, enabled APIs, OAuth client requirements, and supported scopes.

Recommended: Google OAuth for Workspace MCP

Complete the following vendor-side setup before connecting the MCP server.

• Membership in the Google Workspace Developer Preview Program.

• A dedicated Google Cloud project, separate from unrelated production integrations.

• A Google Workspace test mailbox with known test messages.

• A Google Cloud administrator who can configure OAuth consent, enable APIs, and approve the requested scopes.

• Dome's OAuth callback URL: https://api.domesystems.ai/oauth/callback.

• Use an Internal consent screen when every user is in the same Workspace organization.

• If the project uses an External screen while it is in testing, add every smoke-test identity in Google Auth Platform → Audience → Test users.

Enable Gmail and Gmail MCP

In the dedicated Google Cloud project, click Enable on both services: Gmail API (gmail.googleapis.com) and Gmail MCP API (gmailmcp.googleapis.com). Enabling only the Gmail API is not enough: the MCP API is a separate service.

Google's Workspace MCP configuration guide is the authoritative list of API, OAuth, endpoint, and scope requirements.

Configure the OAuth consent screen

In Google Auth Platform, complete Branding, Audience, and Contact Information. Then open Data Access and add only the scopes your first MCP connection needs.

For a read-only Gmail setup, request:

https://www.googleapis.com/auth/gmail.readonly

Do not add compose, label, send, or delete scopes for a read-only assistant. Adding a scope at the OAuth client expands what a future connection can request, even if a particular agent intends not to use it.

Create an OAuth client for an AI agent

Go to Google Auth Platform → Clients → Create client and choose Web application. Add the exact redirect URI below under Authorized redirect URIs:

https://api.domesystems.ai/oauth/callback

Select Use this client for an AI-powered agent before creating the client. Google requires that setting for user-delegated OAuth clients calling Workspace MCP servers. Copy the client ID and secret into a secure secret manager; do not put them in a repository or agent instruction.

If the MCP client supports authorization parameters, request access_type=offline so Google can issue a refresh token. Google notes that an OIDC offline_access scope alone does not do this; use prompt=consent when a user who previously consented needs a new refresh token.

Verify Gmail MCP

Use this checklist to confirm the MCP server is connected with the intended access.

• Connect the server at https://gmailmcp.googleapis.com/mcp/v1 with the new client ID and secret.
• Authorize the dedicated test mailbox.
• Confirm that Gmail MCP tools appear.
• Search for a known test message and read its subject or snippet.
• Confirm that composing, sending, labeling, and deleting are unavailable for the read-only scope.

If authorization succeeds but no expected tools appear, check both enabled APIs and the Google Cloud project associated with the OAuth client. If Google rejects the request, re-check the client type, AI-agent setting, exact redirect URI, test-user access, and consent-screen scopes.

Troubleshooting

If the setup does not work as expected, check these common causes.

• If Google rejects authorization, re-check the Developer Preview enrollment, client type, AI-agent setting, exact redirect URI, test-user access, and consent-screen scopes.
• If authorization succeeds but Gmail MCP tools do not appear, confirm that both the Gmail API and Gmail MCP API are enabled in the Google Cloud project that owns the OAuth client.
• If expected mail is missing, verify the authorized test mailbox and its Gmail scope before widening access.

Next steps

Deploy the Gmail agent template to create a governed agent in Dome that can work with the authorized mailbox under governed rules, with the template's included model, tools, and rules.