gmail-mcp: Instructions file for Codex

Gmail MCP Agent Guidelines

Read this file and README.md before planning or changing the repository.

Workflow

• Default to discovery before implementation: inspect the current repository state, product contract, host approval/retry behavior, and relevant upstream specifications before proposing a code change.
• Preserve existing work. Do not commit, push, create a remote, publish a package, or update external systems without explicit authorization.
• Keep the package small and auditable. Avoid generic Gmail clients, arbitrary REST tools, bundled OAuth frameworks, HTTP transports, token stores, and unrelated Workspace services.
• Update tests and docs with behavior changes. Run the complete credential-free validation before handoff.

Fixed V1 Boundary

The public MCP surface is exactly:

• send_email
• create_label
• update_label
• delete_label

The only OAuth scopes are:

• https://www.googleapis.com/auth/gmail.send
• https://www.googleapis.com/auth/gmail.labels

Do not add inbox/thread reads, search, drafts, reply/forward, attachments, message labeling or other message mutation, synchronization, triggers, or broader Gmail scopes without a new product and security decision.

Internal provider calls required to resolve label identifiers may not become public read tools or return mailbox/message metadata.

Authentication And Runtime

• The runtime is stdio only and must remain compatible with ephemeral MCP host subprocesses. Deployments should use an exact immutable package version through npx or a preinstalled reviewed binary. Prefer preinstalled direct execution when bearer material must remain outside package-install processes.
• Read one fresh host-supplied bearer from GMAIL_OAUTH_BEARER at process startup. A missing, blank, or whitespace-only value must fail closed before tools become usable.
• Never accept, refresh, or persist refresh tokens. Never write access tokens to disk, caches, snapshots, test fixtures, errors, telemetry, or logs.
• Keep provider error bodies and authorization headers out of user-visible errors. Preserve only safe status/category information needed for diagnosis.
• Reserve stdout for MCP JSON-RPC. Send sanitized diagnostics to stderr.