Provider Requests

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/provider-request.ts
• src/mcp/tools.ts
• src/lib/tasks/google.ts
• README.md
• AGENTS.md
• src/app.ts

Provider Requests constitute the communication layer between the e-zer0 MCP server and external email or task services like Google (Gmail) and Microsoft (Outlook/M365). This system normalizes distinct vendor APIs into a unified interface, allowing AI agents to perform operations across different platforms using consistent tool calls.

The architecture ensures that sensitive credentials never leave the self-hosted environment. Every request undergoes strict authorization checks, automated PII redaction, and comprehensive audit logging to maintain security and transparency.

Architecture and Data Flow

The provider request flow begins when an AI agent invokes a tool via the Model Context Protocol. The system validates the agent's permissions, retrieves encrypted credentials, executes the external API call, and sanitizes the response.

Key Components

Token Management and Security

Access tokens for email providers are stored in the Cloudflare D1 database. The system encrypts these tokens at rest using AES-256-GCM with a key stored as a Cloudflare Worker Secret. The getAccountToken function handles the retrieval and decryption process while verifying that the specific MCP client has a valid grant for the requested account.

• Encryption: Uses crypto.subtle (Web Crypto API) for AES-256-GCM.
• Authorization: Checks the mcp_client_accounts table to ensure the client is permitted to access the specific email_account_id.
• Fail-safe: If decryption fails (indicating a key rotation), the system marks the account status as error and prompts for reconnection.

Sources: src/mcp/tools.ts:101-140, AGENTS.md:78-86, README.md:60-70

Request Normalization

The system provides a "Unified Abstraction Layer" so that agents do not need to distinguish between provider-specific implementation details.

Operation	Gmail Implementation	Outlook Implementation
Move to Folder	Applies a label and removes the INBOX label.	Moves the message object to a specific folder ID.
Archive	Removes the INBOX label.	Moves the message to the archive folder.
Draft Reply	Creates a message in the DRAFTS system label.	Creates a message in the Drafts folder.
List Tasks	Fetches from Google Tasks API.	Fetches from Microsoft To Do API.

Sources: README.md:120-135, src/mcp/tools.ts:316-350, AGENTS.md:125-132

Implementation Details

Provider-Specific Fetching

Each provider library implements a specialized fetch wrapper to handle authentication headers and error parsing. For example, the Google Tasks implementation uses a tasksFetch helper.

// Example of a provider-specific fetch implementation
async function tasksFetch(accessToken: string, path: string, options?: RequestInit): Promise<any> {
    const res = await fetch(`${TASKS_API_BASE}${path}`, {
        ...options,
        headers: {
            Authorization: `Bearer ${accessToken}`,
            'Content-Type': 'application/json',
            ...options?.headers,
        },
    });
    if (!res.ok) {
        const err = await res.text();
        throw new Error(`Google Tasks API error (${res.status}): ${err}`);
    }
    return res.status === 204 ? {} : res.json();
}

Sources: src/lib/tasks/google.ts:17-36

Sanitization and Audit

Before any data returned by a provider request reaches the agent, the sanitizeMessages function processes the content. It redacts PII such as credit card numbers and passwords, and scans for prompt injection patterns. Simultaneously, the logAudit function records the action, target, and success status in the audit_logs table.

Summary

Provider Requests serve as the critical gateway between the e-zer0 server and user mailboxes. By abstracting the complexities of Google and Microsoft APIs, the system enables AI agents to interact with diverse email and task environments through a single, secure, and audited protocol.