Connect Google Workspace to Claude: Audit Roles and User Licenses

If your team needs to connect Google Workspace to Claude to audit admin roles, reclaim unused licenses, or automate employee offboarding, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's function-calling capabilities and the massive surface area of Google Workspace's Admin SDKs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on /connect-google-workspace-to-chatgpt-manage-directory-and-groups/ or explore our broader architectural overview on /connect-google-workspace-to-ai-agents-monitor-usage-and-org-units/.

Giving a Large Language Model (LLM) read and write access to an enterprise directory is an engineering challenge fraught with risk. You have to handle domain-wide OAuth delegation, map fragmented JSON schemas to strict MCP tool definitions, and deal with Google's punishing API quotas. Every time Google deprecates a resource or alters an authorization scope, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Google Workspace, connect it natively to Claude Desktop, and execute complex security and compliance workflows using natural language.

The Engineering Reality of the Google Workspace API

A custom MCP server is essentially a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Google Workspace is uniquely painful. You are not just integrating "Google" - you are integrating the Admin Directory API, the Enterprise License Manager API, the Reports API, and the Groups API, all of which act as independent microservices with distinct design patterns.

If you decide to build a custom Google Workspace MCP server, here are the specific integration challenges you will face:

Fragmented Admin SDKs and Authentication Scopes Google Workspace does not have a single unified administrative API. Managing users requires the Directory API, checking product usage requires the Reports API, and allocating seats requires the License Manager API. Each of these requires entirely different OAuth scopes. A custom MCP server must aggregate these endpoints into a cohesive set of tools for Claude, managing a complex token lifecycle that satisfies strict domain-wide delegation rules without over-provisioning access.

Complex Pagination and Partial Responses Google handles massive directories using strict, short-lived pagination cursors (pageToken) and allows for partial responses via the fields parameter. If an LLM attempts to fetch a 10,000-user directory without explicitly managing pagination cursors, the context window will blow up or the API will simply truncate the response. Your MCP server must inject logic to handle these cursors, explicitly instructing the LLM on how to pass them back unchanged for subsequent calls.

Strict Quotas and Rate Limits Google Workspace enforces rigid per-minute and per-day quotas on administrative operations. Notably, read operations and write operations often draw from different quota pools. It is critical to note: Truto does not retry, throttle, or apply backoff on rate limit errors. When the Google Workspace API returns an HTTP 429 error, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller - your agent framework or the Claude client - is responsible for implementing retry and backoff logic.

How Truto's Google Workspace MCP Server Works

Truto eliminates the need to build a custom integration layer by dynamically generating MCP tools based on the connected Google Workspace account.

The key design insight is that tool generation is dynamic and documentation-driven. Rather than hand-coding tool definitions for every Google Workspace endpoint, Truto derives them from existing integration configurations and API documentation records. An MCP server URL is tied to a specific tenant's authenticated Google Workspace session. When Claude connects to this URL, it receives a curated list of tools - generated on the fly - that represent the available API operations.

sequenceDiagram
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Upstream as Google Workspace API

    Claude->>Truto: POST /mcp/:token (tools/list)
    Truto-->>Claude: Returns generated schema for Directory, Licenses, Roles
    
    Claude->>Truto: POST /mcp/:token (tools/call: list_all_admin_users)
    Note over Truto: Validates token<br>Extracts query/body arguments<br>Maps to flat input namespace
    Truto->>Upstream: GET /admin/directory/v1/users
    Upstream-->>Truto: JSON response (users, pageToken)
    Note over Truto: Normalizes HTTP 429 headers if rate limited
    Truto-->>Claude: Formatted JSON-RPC 2.0 response

When Claude calls a tool, the arguments arrive as a single flat object. Truto's MCP router splits them into query parameters and body parameters based on the tool's defined schema, setting context variables before delegating the execution to the underlying proxy API handlers. This means Claude operates on the actual Google Workspace API format without any loss of fidelity.

Creating the Google Workspace MCP Server

Truto allows you to generate a secure MCP server URL for a connected Google Workspace account using either the dashboard or the REST API. Each server is scoped to a specific tenant and authenticates via a unique cryptographic token embedded in the URL.

Method 1: Via the Truto UI

For administrators and operators, the simplest way to generate an MCP server is through the dashboard.

1. Log into Truto and navigate to the Integrated Accounts page for your connected Google Workspace tenant.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration (e.g., limit methods to "read" only, or restrict by specific tags like "directory").
5. Click Create and copy the generated MCP server URL. Keep this URL secure, as it contains the authentication token.

Method 2: Via the Truto API

For developers automating infrastructure, you can programmatically provision MCP servers for your customers. You simply POST to the integrated account's endpoint with your desired configuration.

Request:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Google Workspace Audit Server",
    "config": {
      "methods": ["read", "update"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Response:

{
  "id": "mcp_abc123",
  "name": "Google Workspace Audit Server",
  "config": {
    "methods": ["read", "update"]
  },
  "expires_at": "2026-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have the Truto MCP URL, you need to register it with your Claude client. The URL handles the transport layer (Server-Sent Events or HTTP POST depending on the client) and the JSON-RPC protocol automatically.

Method A: Via the Claude Desktop UI

If you are using Claude Desktop or an enterprise workspace that supports visual connector management:

1. Open Claude Settings.
2. Navigate to Integrations or Connectors (depending on your tier).
3. Click Add MCP Server or Add custom connector.
4. Paste the Truto MCP server URL (https://api.truto.one/mcp/...) and click Add.
5. Claude will immediately handshake with the server, pull the available Google Workspace tools, and make them available in the chat interface.

Method B: Via Manual Config File

For developers running custom agents or configuring Claude Desktop locally via the filesystem, you can add the server to your claude_desktop_config.json file. Because Truto's MCP endpoint is a standard HTTP POST interface, you can wrap it using the official Model Context Protocol SSE transport utility.

Locate your Claude config file (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the following:

{
  "mcpServers": {
    "google-workspace-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "--url",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

Restart Claude Desktop. The agent will read the config, execute the npx command to bridge the SSE connection, and initialize the Google Workspace tools.

Hero Tools for Google Workspace Auditing

Truto exposes the entirety of the Google Workspace API, but for security and license auditing, specific endpoints provide the most leverage. Here are the hero tools automatically generated by Truto's MCP integration.

list_all_admin_users

This tool retrieves the master directory of users. It handles Google's pagination and returns an array of user objects including identifiers, organizational units, and suspension status.

Contextual Usage Notes: When querying large directories, instruct Claude to use the limit parameter and explicitly pass the next_cursor back if it needs to paginate through thousands of employees.

"Fetch the first 100 users from the Google Workspace directory and list their primary email addresses and current status."

list_all_admin_roles

Retrieves all roles defined in the Google Admin Directory for the authenticated customer. This includes system-defined roles (like Super Admin) and custom RBAC roles.

Contextual Usage Notes: Use this to map role IDs to human-readable names before auditing role assignments.

"List all custom roles configured in our Google Workspace environment so we can review their names and descriptions."

list_all_admin_role_assignments

Retrieves the actual mapping of users to admin roles. This is the critical endpoint for security audits, allowing you to see exactly who holds elevated privileges.

Contextual Usage Notes: Because the API returns role IDs and user IDs, Claude typically needs to orchestrate a sequence: fetch the assignments, then map those IDs back to human-readable emails via get_single_admin_user_by_id.

"Get all role assignments in the directory and identify which specific users have been assigned the Super Admin role."

list_all_admin_licenses

Lists Google Workspace product licenses assigned to users. This tracks exactly who is consuming paid seats for products like Google Workspace Enterprise, Google Vault, or Cloud Identity.

Contextual Usage Notes: You must provide a product_id (e.g., Google-Apps). Claude can use this to identify users consuming expensive SKUs.

"Check the license assignments for the Google-Apps product ID and list all users who currently hold a paid license."

list_all_admin_usage_reports

Fetches daily usage metrics for all users, including last login time, Gmail interactions, and Drive activity.

Contextual Usage Notes: Google's reporting API requires a specific date parameter in YYYY-MM-DD format. The data is usually delayed by 2 - 3 days, so instruct Claude to query a date from earlier in the week.

"Pull the admin usage reports for yesterday and identify any users who have not logged in for over 90 days."

update_a_admin_user_by_id

Updates an existing user record. This allows Claude to take remedial action based on its audits, such as suspending inactive users, enforcing password resets, or changing organizational units.

Contextual Usage Notes: This is a destructive operation. In production MCP configurations, it is heavily recommended to gate this tool behind a "human-in-the-loop" approval step inside your agent framework, or to scope the MCP server to read-only methods.

"Suspend the user with the ID 10938475629 by updating their suspended status to true, as they failed the security audit."

For a complete inventory of available Google Workspace tools, including endpoints for Group management, OAuth tokens, and Organizational Units, visit the Google Workspace integration page.

Workflows in Action

When you connect Claude to Google Workspace via Truto, you unlock autonomous workflows that string multiple tools together to solve complex IT tasks.

Workflow 1: Auditing Inactive Users and Reclaiming Licenses

IT administrators frequently need to find users who have left the company or abandoned their accounts, in order to suspend them and reclaim expensive software licenses.

"Analyze our Google Workspace usage. Find users who have not logged in over the last 90 days based on usage reports, check if they hold a paid Google Workspace license, and if they do, suspend their accounts to free up the seats."

Step-by-step Execution:

1. Claude calls list_all_admin_usage_reports passing a date from 90 days ago, filtering for users with zero recent login activity.
2. Claude extracts the user IDs of the inactive accounts.
3. Claude iterates over those IDs, calling list_all_admin_licenses to verify which users are consuming premium SKUs.
4. Claude calls update_a_admin_user_by_id for the offending accounts, passing {"suspended": true} in the body schema to lock the accounts.
5. Claude outputs a markdown table summarizing the suspended emails and the number of licenses successfully reclaimed.

Workflow 2: Privileged Access Review

Security engineers conduct quarterly audits to ensure that "Super Admin" privileges haven't suffered from scope creep.

"Conduct a security review of our admin roles. Identify all users holding the Super Admin role, verify their organizational unit, and flag any accounts that are not in the 'IT Security' OU."

Step-by-step Execution:

1. Claude calls list_all_admin_roles to lookup the internal roleId corresponding to "Super Admin".
2. Claude calls list_all_admin_role_assignments using that role ID to get the list of assigned assignedTo identifiers.
3. For each identifier, Claude calls get_single_admin_user_by_id to retrieve the full user object, specifically checking the orgUnitPath field.
4. Claude evaluates the paths. If a user is in /Sales or /Contractors instead of /IT Security, it flags them.
5. Claude returns a final audit report detailing the unauthorized privileged users, providing the exact IDs needed for remediation.

Security and Access Control

Exposing an enterprise directory to an LLM requires strict boundary setting. Truto's MCP servers provide multiple layers of access control configured at the token level:

• Method Filtering: Restrict the server to specific operation types. By configuring methods: ["read"], Claude can list users and audit roles, but the system will reject any attempts to call create, update, or delete tools, eliminating the risk of accidental modifications.
• Tag Filtering: Group tools by functional area. You can restrict the MCP server to only expose tools tagged with directory or security, preventing Claude from wandering into Google Calendar or Drive APIs if they happen to be enabled on the same integration.
• API Token Authentication (require_api_token_auth): For shared environments, you can enable this flag. The MCP URL alone will no longer be sufficient; the client must also pass a valid Truto API token in the Authorization header, binding the tool execution to an authenticated user identity.
• Ephemeral Servers (expires_at): Grant temporary access by setting an ISO datetime expiration. Once the time passes, Truto's infrastructure automatically cleans up the KV storage and database records, instantly revoking the AI's access to Google Workspace.

Building Agentic IT Operations

Connecting Claude to Google Workspace via MCP fundamentally shifts how IT and security teams operate. Instead of clicking through complex admin consoles, writing custom Python scripts, or managing fragile OAuth refresh loops, you can deploy natural language agents to monitor directory health and enforce compliance policies.

By leveraging Truto's managed MCP architecture, you sidestep the massive engineering burden of maintaining Google Workspace API connections. You get dynamic tool generation, normalized error handling, and robust security constraints out of the box. Whether you are building an internal security bot or integrating agentic features into your B2B SaaS product, Truto handles the infrastructure so you can focus on the workflow.