Policy reference

Every field in the policy file, CLI flag, and environment variable, explained.

The policy file is a JSON file with two top-level keys: "server" for global settings and "services" for per-service configuration.

"server" object

{
  "server": {
    "read_only": false,
    "rate_limit_rpm": 120,
    "allowed_origins": ["internal.corp.com"],
    "credentials_file": "/path/to/credentials.json",
    "project_id": "my-project-123456"
  }
}

"services" array

Only services listed here are exposed as MCP tools. Everything else is denied.

Available services

Any Google Workspace API discoverable through the Google Discovery Service can be used. Common aliases:

Gmail label policy

The allowed_labels field restricts which Gmail labels the agent can access. When set, the server injects a label filter into search queries and validates message access against the allowed list.

{
  "services": [
    {
      "name": "gmail",
      "allowed_labels": ["INBOX", "SENT", "IMPORTANT"],
      "denied_methods": ["messages.delete", "messages.trash"]
    }
  ]
}

Per-service rate limits

Override the global rate limit for specific services to respect Google API quotas:

{
  "services": [
    {
      "name": "sheets",
      "rate_limits": {
        "requests_per_minute": 60
      }
    }
  ]
}

"constraints" -- Parameter-level access controls

Constraints let you restrict which values a parameter can take. Each constraint specifies a parameter name, a list of allowed values, and an access level.

Constraints are generic -- the same mechanism works for any service and any parameter. The server validates constraint values against the actual API call at runtime.

How constraints work

• Path/query parameters: the value provided by the agent must be in the constraint's values list. If the constraint is read-only, write operations are denied.
• Body parameters (with "location": "body"): on write operations, the body field must be present and its values must all be in the allowed list. On read/list operations, the server injects a query filter to restrict results.
• Parent ancestry: For Drive folder constraints, the server recursively checks parent folders. A file in a subfolder of an allowed folder inherits access.
• Multiple constraints on the same parameter are merged -- all values across constraints are allowed, and each value inherits the access level of its constraint.

Examples

Drive -- restrict to specific folders:

{
  "services": [
    {
      "name": "drive",
      "constraints": [
        { "param": "parents", "values": ["folder-abc"], "access": "read-only", "location": "body" },
        { "param": "parents", "values": ["folder-xyz"], "access": "read-write", "location": "body" }
      ]
    }
  ]
}

Calendar -- restrict to specific calendars:

{
  "services": [
    {
      "name": "calendar",
      "constraints": [
        { "param": "calendarId", "values": ["primary"], "access": "read-write" },
        { "param": "calendarId", "values": ["holidays@group.calendar.google.com"], "access": "read-only" }
      ]
    }
  ]
}

Sheets -- restrict to a specific spreadsheet:

{
  "services": [
    {
      "name": "sheets",
      "constraints": [
        { "param": "spreadsheetId", "values": ["1BxiMVs0XRA..."], "access": "read-only" }
      ]
    }
  ]
}

Slides -- protect templates:

{
  "services": [
    {
      "name": "slides",
      "constraints": [
        { "param": "presentationId", "values": ["template-id-123"], "access": "read-only" }
      ]
    }
  ]
}

Gmail -- block dangerous methods:

{
  "services": [
    {
      "name": "gmail",
      "allowed_labels": ["INBOX", "SENT"],
      "denied_methods": [
        "messages.delete", "messages.trash", "messages.batchDelete",
        "settings.updateAutoForwarding",
        "settings.delegates.create",
        "settings.forwardingAddresses.create"
      ]
    }
  ]
}

Evaluation order

Every request passes through these checks in order. All checks must pass -- the first failure stops evaluation and denies the request.

1. Service allow-list -- Is the service listed in "services"? Unlisted services are denied entirely.
2. Read-only -- Is the service (or server) read-only? If yes, non-GET methods are denied.
3. Denied methods -- Is the method in the denied_methods list? Uses suffix matching: "messages.send" in the denylist matches API method "users.messages.send".
4. Label policy -- For Gmail, is the message's label in allowed_labels?
5. Constraints -- Do the parameter values match the allowed list? Is the access level sufficient for the operation?

There is no override mechanism -- a method denied at step 2 cannot be re-allowed at step 5. Each layer can only narrow access, never widen it.

Every denial includes a Fix: hint with the exact JSON snippet to add or change in the policy file.

Note: This policy engine is specific to this MCP server. The upstream google-workspace crate (gws CLI) has no policy or permission model -- it relies solely on OAuth scopes.

CLI flags

Server

Policy tools

Templates

Live policy reload

When running with --http and --policy, the server reloads the policy file on SIGHUP without restarting:

kill -HUP $(pidof mcp-google-workspace)

Failed reloads log an error and keep the current policy. Not available in stdio mode.

Audit log

The --audit-log flag writes a JSONL file with one entry per API call:

{"timestamp":"1718745600.000","action":"allowed","service":"drive","resource":"files","method":"list","http_method":"GET","tool":"gws_drive_list","status":200,"duration_ms":142}
{"timestamp":"1718745601.000","action":"denied","service":"docs","resource":"documents","method":"create","reason":"Service 'docs' is read-only"}

Request explanation

Every write operation (POST, PUT, PATCH, DELETE) includes an _explanation field in the response's structuredContent:

{
  "structuredContent": {
    "_explanation": "Create drive/files.create (POST): name=\"report.pdf\", in folder folder-xyz",
    "id": "...",
    "name": "report.pdf"
  }
}

This helps agents surface what happened to the user in plain language.

Environment variables

Policy JSON fields take precedence where both are available.

Credentials

Quota and project

Observability

Edit this page on GitHub