How to Integrate Google APIs With AI Agents Using MCP: Hosted Servers, OAuth, and Multi-Tenant Setup

TL;DR

• Google now runs hosted, remote MCP servers for Gmail, Drive, Calendar, Sheets, Docs, Slides, and Chat, so an agent can connect over Streamable HTTP without you standing up any backend code.
• Every tool call still passes through OAuth 2.0. The agent only ever sees what the signed in user has explicitly granted, nothing more.
• Hosted servers get you running in an afternoon but lock you into Google’s fixed toolset. A custom MCP server buys flexibility at the cost of writing and maintaining your own auth, retries, and schema code.
• Once an agent serves more than one customer, token storage, per tenant isolation, and rate limit handling become the actual engineering problem, which is where an integration layer like Corsair fits in.

If you are building an AI agent that needs to read a Gmail thread, pull a file from Drive, or check someone’s calendar, Model Context Protocol (MCP) is now the most direct way to wire that up. Google publishes hosted, remote MCP servers for Gmail, Drive, Calendar, Sheets, Docs, Slides, Chat, and the People API, which means an agent built with Claude, Gemini CLI, or Google Antigravity can call these tools over a standard HTTP connection instead of you writing a custom integration against each REST API.

This guide walks through how Google’s hosted Google Workspace MCP servers actually work, what tools they expose, how to configure and authenticate against them, when a custom MCP server makes more sense, and what tends to break once real users and real token volume show up. The last section covers what changes once you are running these integrations across many customer accounts instead of just your own.

How Google Workspace MCP Servers Work: Hosts, Clients, and the Request Lifecycle

Google Workspace MCP servers work as remote, product specific endpoints hosted on Google’s own infrastructure that your AI agent talks to over HTTPS, rather than a protocol you run yourself. Gmail, Drive, Calendar, and Sheets each have their own dedicated MCP endpoint, and a single conversation can call several of them in sequence.

The architecture has four participants:

• MCP host: the AI application itself, such as Claude Desktop, Gemini CLI, or Google Antigravity. It talks to the user and to the underlying LLM.
• MCP client: a component inside the host that keeps a dedicated connection open to one MCP server at a time.
• Google Workspace MCP server: the remote program Google hosts that exposes tools over standardized HTTP endpoints, for example https://gmailmcp.googleapis.com/mcp/v1 or https://drivemcp.googleapis.com/mcp/v1.
• Google Workspace APIs: the backend services, like the Gmail API or Drive API, that actually execute the read or write once the MCP server authorizes the request.

Communication runs on two layers. The transport layer uses Streamable HTTP (HTTP POST requests, optionally with server sent events) rather than the STDIO transport that local MCP servers typically use. The data layer runs standard JSON RPC 2.0 messages for discovery, tool calls, and real time notifications when a server’s available tools change.

A typical request moves through six steps: the client requests the tool list, the server responds with the available tools and their schemas, the LLM picks a tool and fills in parameters, the client sends a tools/call request, the MCP server validates the OAuth token and calls the underlying Google API, and the result flows back through the server into the LLM’s context so it can generate a response for the user.

What Tools Google’s Hosted MCP Servers Expose for Gmail, Drive, Calendar, and Sheets

Each Google Workspace product ships its own MCP server with a tailored set of read and write tools, discovered dynamically through a tools/list call rather than hardcoded into your agent. The schema for each tool includes a name, a description the LLM uses to decide when to call it, and a JSON Schema defining its inputs.

On the Gmail MCP server, the main tools cover:

• search_threads and get_thread or get_message for finding and reading conversations
• create_draft for drafting a reply or new email without sending it automatically
• list_drafts and list_labels for inventory
• label_message and label_thread (plus their unlabel counterparts) for organization

On the Google Drive MCP server, you get:

• search_files for querying My Drive and shared drives
• read_file_content and download_file_content for pulling document data
• get_file_metadata and get_file_permissions for inspecting sharing and access
• create_file, copy_file, and list_recent_files for file management

On the Google Calendar MCP server, tools include list_events, search_events, get_event, create_event, update_event, delete_event, suggest_time for finding open slots, and respond_to_event for RSVPs.

On the Google Sheets MCP server, you get get_values and update_values for reading and writing cell ranges, get_spreadsheet for structure and metadata, update_formulas, and insert_dimension for adding rows or columns.

If you only need one of these products, it is worth reading the deeper walkthroughs: our guide to the Gmail MCP server covers connecting an agent to email specifically, and our Google Drive MCP server guide walks through a hands on setup in Claude Code.

How to Configure Google’s Hosted MCP Servers and Connect Them to Your Agent

Configuring Google’s hosted MCP servers means enabling the right services in Google Cloud, setting up OAuth consent and scopes, generating credentials, and pointing your client’s config file at the remote endpoints. Note that Google Workspace MCP support currently sits inside the Google Workspace Developer Preview Program, so your account needs to be enrolled before any of this works.

The setup breaks down into five steps:

1. Enable the backend APIs and the matching MCP services in your Google Cloud project. You need both the standard API (gmail.googleapis.com, drive.googleapis.com) and its dedicated MCP service (gmailmcp.googleapis.com, drivemcp.googleapis.com):
   gcloud services enable gmail.googleapis.com drive.googleapis.com \
calendar-json.googleapis.com sheets.googleapis.com \
gmailmcp.googleapis.com drivemcp.googleapis.com \
calendarmcp.googleapis.com sheetsmcp.googleapis.com \
--project=PROJECT_ID
2. Configure the OAuth consent screen, set your app name and support email, choose Internal or External audience, and add the specific scopes each service needs, for example gmail.readonly, drive.file, or spreadsheets.
3. Generate OAuth 2.0 credentials under Google Auth Platform, choosing Web Application for GUI clients or Desktop App for CLI tools like Gemini CLI.
4. Point your client’s config file at the remote servers. Most MCP hosts use a JSON file mapping each service to its server URL and credentials:
   {
"mcpServers": {
"gmail": {
"serverUrl": "https://gmailmcp.googleapis.com/mcp/v1",
"oauth": { "clientId": "YOUR_CLIENT_ID", "clientSecret": "YOUR_CLIENT_SECRET" }
}
}
}
5. Authenticate and verify. In a GUI client, you typically open Settings, find Connectors, and click Authenticate for each service to complete the browser OAuth flow. In a CLI client, a command like /mcp auth gmail does the same thing. Once connected, a quick prompt like “summarize my last five emails” confirms the tool calls are actually working end to end.

Hosted MCP Server or Custom Server: How to Decide

The choice between Google’s hosted MCP servers and building your own comes down to how much control you need versus how fast you want to ship. Hosted servers win on speed; a custom server wins on flexibility.

Reasons to use Google’s hosted servers:

• Zero backend code: you configure and authenticate, Google maintains the tool definitions and uptime
• Direct OAuth handling: the agent inherits the exact permissions of the signed in Google account with no intermediate credential broker
• Fast to ship: a working integration is a configuration file away, not a development project

Reasons to build a custom MCP server instead:

• You need to combine Google data with internal databases or non Google APIs in a single tool call
• You want to filter, reshape, or sanitize raw API output before it reaches the LLM’s context
• You need tool signatures, validation rules, or output formats that Google’s standard schema does not offer
• You are running locally over STDIO for a single desktop agent rather than serving multiple clients remotely

In practice, most teams start with the hosted servers because the time to first working agent is so much shorter, then layer in custom logic later only where the standard toolset genuinely falls short.

Where Google MCP Integrations Break in Production: Tokens, Permissions, and Quotas

The failures that show up once real traffic hits a Google MCP integration tend to fall into three buckets: authentication, permissions, and quota limits. We cover each of these in depth elsewhere, so here is the short version.

On authentication: access tokens expire hourly and need a refresh token to renew automatically. Refresh tokens themselves can go invalid for several ordinary reasons: the user revokes access, the token sits unused for six months, the user changes their Gmail password, or the OAuth consent screen is still in Testing mode, which caps refresh tokens at seven days. Our Google API authentication for AI applications guide covers the full token lifecycle and storage patterns.

On permissions: Google lets users grant only a subset of the scopes you requested, so a tool call can fail with a permission error even though the user technically connected their account. Shared Drive membership rules and file level ACLs add another layer that is easy to miss during testing with your own account.

On quotas: Gmail enforces per user sending and concurrency caps, Drive enforces storage and item count limits, and both return 429 or 403 errors under load that need exponential backoff rather than an immediate retry. Our Google API quotas and rate limits guide goes deep on per user versus per project limits and how to budget for them in a multi tenant agent.

Running Google MCP Integrations Across Many Customers With Corsair

Running Google MCP integrations across many customers means solving credential isolation, token refresh, and rate limiting at the platform level rather than per agent, and that is the gap Corsair is built to close. MCP itself is just an interface standard. It defines how an agent discovers and calls tools, but it does not store credentials, refresh tokens, or isolate one customer’s data from another’s, so a team building a real multi tenant product ends up writing that infrastructure by hand regardless of which MCP servers they connect to.

Corsair sits between your agent and Google’s APIs as a centralized control plane. A few things it handles directly:

• Tenant level credential isolation: OAuth tokens are encrypted and partitioned per tenant using a key encryption key you control, so one customer’s session structurally cannot reach another customer’s data.
• Automated token refresh: Corsair requests offline access on first authorization, stores the refresh token, and exchanges it for a new access token in the background whenever the old one expires, without interrupting the agent mid task.
• Server side secret isolation: raw tokens and client secrets never enter the LLM’s context window. The agent only ever sees tool names, typed parameters, and sanitized results, which closes off a common prompt injection path for credential leakage.
• Local caching: repeated reads during multi step agent reasoning hit a local, tenant partitioned cache synced through webhooks and polling instead of hitting Google’s API on every single query, which keeps you well inside rate limits.
• Human in the loop gates: destructive actions, like permanently deleting a Drive file or sending an email, can require explicit review before they execute.

Developers get this through typed TypeScript packages like @corsair-dev/gmail and @corsair-dev/googledrive, exposed through an MCP gateway, a REST API, or framework adapters for tools like LangChain and LlamaIndex, so the same Google Workspace connection works whether you are calling it from an agent, a backend job, or a customer facing dashboard.

If you are past the point of a single account demo and into serving real customers, Corsair is worth a look. It is an open source, self hostable integration layer that handles multi tenant OAuth, Google Workspace connectors, and the credential isolation covered in this guide out of the box, so you can spend your engineering time on what the agent actually does rather than rebuilding this plumbing yourself. You can explore it at corsair.dev.

FAQs

Do I need to build my own MCP server to connect an agent to Gmail or Drive?
No, not for standard use cases. Google publishes hosted, remote MCP servers for Gmail, Drive, Calendar, Sheets, Docs, Slides, and Chat that you connect to through configuration rather than custom code. A custom server only becomes necessary when you need to combine Google data with other systems or customize the tool schema beyond what Google exposes.

Is Google’s Workspace MCP support production ready or still in preview?
As of this writing, Google Workspace MCP servers are part of the Google Workspace Developer Preview Program, so your account needs to be enrolled before you can enable the MCP services, and behavior or endpoints may still change before general availability.

What happens if a user only grants some of the requested OAuth scopes?
Google’s consent screen allows granular approval, so a user can approve read access to Gmail while declining compose access, for example. Your integration needs to check the granted scopes in the token response and handle a tool call failing gracefully rather than assuming every requested scope was approved.

Can one AI agent safely serve multiple customers’ Google accounts?
Yes, but only if credentials are isolated per tenant at the database layer, not just filtered in application code. Each customer’s OAuth tokens need their own encrypted storage and their own refresh lifecycle so that a bug in one tenant’s session can never read or write another tenant’s Gmail or Drive data.

What is the difference between MCP and calling the Google API directly?
A direct API integration means your code calls Gmail or Drive endpoints and handles the request and response shape yourself. MCP adds a standard discovery and invocation layer on top, so any MCP compatible agent can find and call the same tools through tools/list and tools/call without you writing agent specific glue code for each one.