Google Workspace MCP Admin Server

A read-only Model Context Protocol server for investigating privileged Google Workspace users through narrow, policy-scoped tools.

The server treats model-driven administration as distributed systems work. MCP is the tool boundary, OAuth/OIDC is the authority boundary, a gateway is defense in depth, and OpenTelemetry connects the execution path without recording Workspace content.

Current Status

Experimental, read-only prototype. Local stdio is a credential-free synthetic demo. The authenticated HTTP entrypoint can hold Google credentials on a separate service host. Live Google and identity-provider integration have not yet been validated. HTTP alone does not isolate credentials: the agent must not be able to access the service's files, environment, or signing identity.

Version 0.2 uses the official TypeScript SDK for modern MCP and legacy stdio clients.

Implemented:

• profile-scoped tool discovery with a second authorization check at invocation

• minimum Google OAuth scopes derived from the final exposed tool set

• exact user, group, membership, and bounded Admin audit reads

• structured MCP outputs with pagination and completeness markers

• deterministic privileged-user findings based on provider evidence

• W3C traceparent propagation across MCP, policy, and Google API spans

• content-free telemetry and redacted structured logs

• provider-boundary, policy, trace, mapping, and redaction tests

• synthetic-only stdio, with startup rejection of Google key-bearing configurations

• stateless HTTP with per-request JWT access-token verification and scoped discovery

• OAuth protected-resource metadata, trusted Host/Origin checks, and bounded request bodies

Not implemented:

• demonstrated deployment isolation and live identity-provider integration

• per-investigation target/field grants and durable principal audit records

• gateway deployment policy

• delegated or on-behalf-of token exchange

• durable idempotency and approval-gated writes

Those boundaries are specified in Enterprise Runtime and sequenced in the Roadmap.

The original Python implementation remains available at the python-v0.1 tag.

Related MCP server: gg-mcp

Admin Workflow

The smallest coherent workflow is a privileged-user investigation:

identify subject
  -> inspect exact user
  -> inspect group memberships
  -> search a bounded Admin audit window
  -> return evidence and page completeness
  -> flag only deterministic privilege-state conflicts

workspace_privileged_user_review composes that workflow without exposing the broader inventory catalog under the default risk profile.

Tools

List tools return this explicit page contract:

{
  "items": [],
  "resultCount": 0,
  "nextPageToken": "opaque-provider-token",
  "complete": false
}

Audit event parameters are excluded by default. Callers must explicitly request them with includeParameters: true.

Under risk, continue review evidence with membershipPageToken and activityPageToken, using the respective result's nextPageToken. Keep the subject, window, and limits unchanged. Omitted tokens fetch first pages; results describe the current pages, not an accumulated investigation or a consistent provider snapshot.

Security Profiles

WORKSPACE_MCP_ALLOWED_TOOLS can narrow a profile but cannot expand it. WORKSPACE_MCP_GRANTED_SCOPES is also an upper bound. The server removes unused grants before creating the Google credential.

See the full Tool Catalog and Agent Containment Model.

Quick Start

Requirements:

• Node.js 22 or newer

• no Google account, credential, or paid model is needed for the local demo

npm ci
npm run typecheck
npm test
npm run build
npm run dev

The stdio demo uses admin@example.test (or synthetic-admin) and an audit event at 2026-09-01T12:00:00Z. Use a window containing that time for the review tool. It is fixed test data, not a live Workspace connection. Inventory queries and unknown fixture subjects are rejected rather than simulated as successful reads.

Example MCP client configuration after npm run build:

{
  "mcpServers": {
    "workspace-admin": {
      "command": "node",
      "args": ["/absolute/path/to/workspace-admin-mcp/dist/index.js"],
      "env": {
        "WORKSPACE_MCP_DATA_SOURCE": "synthetic"
      }
    }
  }
}

Migration: stdio no longer accepts live Google credentials. Remove Google keys from MCP client configuration and its inherited environment. For the HTTP service, see HTTP Deployment. .env.example is service-side configuration, not client configuration; environment files are not loaded automatically.

Observability

Normal dev and start commands do not install an exporter. To export manual spans to an OTLP collector:

$env:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://localhost:4318/v1/traces"
npm run dev:traced

Span attributes are allowlisted operational metadata: tool name, policy decision, provider operation, result count, completeness, and error type. Prompts, tool arguments, emails, tokens, page tokens, and response bodies are excluded. Only traceparent is accepted from inbound MCP metadata; tracestate and baggage are dropped.

Design Documents

• Architecture

• Security

• Agent Containment

• Enterprise Runtime

• Roadmap

• Validation