Google OAuth

Use the google strategy to authenticate users with their Google accounts. This is a preset of the generic OAuth flow with Google’s endpoints pre-configured.

Creating a Google OAuth Client

Go to the Google Cloud Console
Select or create a project
Navigate to APIs & Services > Credentials
Click Create Credentials > OAuth client ID
For Application type, select Web application
Configure the authorized redirect URI:
- For production: https://your-domain.com/oauth/provider-callback
- For local development: http://localhost:3000/oauth/provider-callback
Copy the Client ID and Client Secret

Environment Setup

AUTH_STRATEGY=google
OAUTH_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
OAUTH_CLIENT_SECRET=GOCSPX-your-secret
OAUTH_SCOPES=openid email profile
OAUTH_REDIRECT_URI=https://your-server.com/oauth/provider-callback

Preset Values

Setting	Default
Accounts URL	`https://accounts.google.com`
Authorization URL	`https://accounts.google.com/o/oauth2/v2/auth`
Token URL	`https://oauth2.googleapis.com/token`
Default scopes	`openid email profile`

You can override any preset with explicit OAUTH_* values.

Example: Google Sheets + Drive

AUTH_STRATEGY=google
OAUTH_CLIENT_ID=123456789-abc.apps.googleusercontent.com
OAUTH_CLIENT_SECRET=GOCSPX-your-secret
OAUTH_SCOPES=openid email profile
OAUTH_REDIRECT_URI=https://my-mcp.example.com/oauth/provider-callback

Available Scopes

Scope	Description
`https://www.googleapis.com/auth/spreadsheets`	Read/write Google Sheets
`https://www.googleapis.com/auth/drive.readonly`	Read Google Drive files
`https://www.googleapis.com/auth/drive`	Full Google Drive access
`https://www.googleapis.com/auth/gmail.readonly`	Read Gmail
`openid`	OpenID Connect authentication
`email`	Access email address
`profile`	Access profile information

Tool Context

When AUTH_STRATEGY=google, successful authentication populates the tool context with:

context.providerToken — the Google access token
context.resolvedHeaders — { Authorization: "Bearer <google-access-token>" }
context.provider — provider info object with accessToken, refreshToken, expiresAt, scopes
context.authStrategy — "google"

Example Tool

import { defineTool, assertProviderToken } from "@phake/mcp";
import { z } from "zod";

const readSheetTool = defineTool({
  name: "read_sheet",
  description: "Read data from a Google Sheet",
  inputSchema: z.object({
    spreadsheetId: z.string().describe("The spreadsheet ID"),
    range: z.string().describe("The cell range (e.g., Sheet1!A1:B10)"),
  }),
  requiresAuth: true,
  handler: async (args, context) => {
    assertProviderToken(context);
    
    const response = await fetch(
      `https://sheets.googleapis.com/v4/spreadsheets/${args.spreadsheetId}/values/${args.range}`,
      { headers: context.resolvedHeaders }
    );
    return await response.json();
  },
});

Additional Options

Offline Access

To receive a refresh token (for long-lived access), add access_type=offline to extra auth params:

OAUTH_EXTRA_AUTH_PARAMS=access_type=offline&prompt=consent

To force the consent screen to appear every time:

OAUTH_EXTRA_AUTH_PARAMS=prompt=consent

Getting User Info

Use context.getUser() to fetch the authenticated user’s profile from Google:

const getProfileTool = defineTool({
  name: "get_profile",
  description: "Get the authenticated user's Google profile",
  inputSchema: z.object({}),
  requiresAuth: true,
  handler: async (_args, context) => {
    const { data: user, error } = await context.getUser();
    if (error) {
      return { error };
    }
    return user;
  },
});

Or use the standalone getUser helper with USERINFO_ENDPOINTS:

import { getUser, USERINFO_ENDPOINTS, assertProviderToken } from "@phake/mcp";

handler: async (_args, context) => {
  assertProviderToken(context);
  const user = await getUser(context.providerToken, USERINFO_ENDPOINTS.google);
  return user;
}

The USERINFO_ENDPOINTS constant provides pre-configured URLs:

Provider	Endpoint
`google`	`https://www.googleapis.com/oauth2/v2/userinfo`
`github`	`https://api.github.com/user`

Access Google ID Token Claims

When using Google OAuth, the id_token is automatically decoded and available via context.provider?.idTokenClaims:

const getProfileTool = defineTool({
  name: "get_profile",
  description: "Get the authenticated user's profile",
  inputSchema: z.object({}),
  requiresAuth: true,
  handler: async (_args, context) => {
    const claims = context.provider?.idTokenClaims;
    if (!claims) {
      return { error: "No ID token claims available" };
    }
    // claims.email, claims.name, claims.sub, etc.
    return {
      email: claims.email,
      name: claims.name,
      picture: claims.picture,
    };
  },
});

Common Google ID token claims:

email - User’s email address
name - User’s full name
picture - URL to user’s profile picture
sub - User’s unique Google ID

Get Started

Core Concepts

Authentication

Guides

Configuration

Creating a Google OAuth Client

Environment Setup

Preset Values

Example: Google Sheets + Drive

Available Scopes

Tool Context

Example Tool

Additional Options

Offline Access

Getting User Info

Access Google ID Token Claims

​Creating a Google OAuth Client

​Environment Setup

​Preset Values

​Example: Google Sheets + Drive

​Available Scopes

​Tool Context

​Example Tool

​Additional Options

​Offline Access

​Force Consent

​Getting User Info

​Access Google ID Token Claims

Creating a Google OAuth Client

Environment Setup

Preset Values

Example: Google Sheets + Drive

Available Scopes

Tool Context

Example Tool

Additional Options

Offline Access

Force Consent

Getting User Info

Access Google ID Token Claims