Skip to main content
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

  1. Go to the Google Cloud Console
  2. Select or create a project
  3. Navigate to APIs & Services > Credentials
  4. Click Create Credentials > OAuth client ID
  5. For Application type, select Web application
  6. Configure the authorized redirect URI:
    • For production: https://your-domain.com/oauth/provider-callback
    • For local development: http://localhost:3000/oauth/provider-callback
  7. 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

SettingDefault
Accounts URLhttps://accounts.google.com
Authorization URLhttps://accounts.google.com/o/oauth2/v2/auth
Token URLhttps://oauth2.googleapis.com/token
Default scopesopenid 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

ScopeDescription
https://www.googleapis.com/auth/spreadsheetsRead/write Google Sheets
https://www.googleapis.com/auth/drive.readonlyRead Google Drive files
https://www.googleapis.com/auth/driveFull Google Drive access
https://www.googleapis.com/auth/gmail.readonlyRead Gmail
openidOpenID Connect authentication
emailAccess email address
profileAccess 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:
ProviderEndpoint
googlehttps://www.googleapis.com/oauth2/v2/userinfo
githubhttps://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