Agent Configuration UI

The Agent Configuration UI provides a centralized interface for administrators to create, manage, and audit Model Context Protocol (MCP) agents. It allows users to generate secure credentials (Client ID and Secret) for AI tools and define granular access permissions for connected email and calendar accounts.

This system ensures that AI agents interact with user data through a secure bridge, enforcing PII redaction and providing a full audit trail for every action.

Sources: README.md:9-25, src/routes/agents.tsx:1-15

Core Functionality

The UI handles the lifecycle of agent credentials and their associated permissions. It uses server-side rendering (SSR) via Hono JSX to provide a lightweight, no-client-side-JS experience.

Agent Lifecycle Management

Administrators perform the following actions within the agents route:

• Creation: Generates a unique client_id and a client_secret. The secret is hashed using a salt before storage in the D1 database.
• Editing: Updates the agent's display name and modifies account access grants.
• Revocation: Sets the is_active status to 0, immediately blocking the agent from the MCP transport.

Sources: src/routes/agents.tsx:162-212, src/routes/agents.tsx:219-222, src/lib/crypto.ts

Permission Model

Permissions are granted per-account and per-service. The UI presents a matrix where administrators select:

• Email Access: Grants permission to read, search, and manage email (e.g., move to folders, create drafts).
• Calendar Access: Grants read-only access to calendar events and occurrences.

Calendar grants are separate from mailbox grants and default to off. Empty selections are valid, meaning an agent can authenticate but has no data access.

Sources: src/routes/agents.tsx:25-83, README.md:120-130

Architecture and Data Flow

The following diagram illustrates the process of creating a new agent and persisting its credentials and permissions.

The diagram shows the sequence of credential generation and database persistence during agent creation.
Sources: src/routes/agents.tsx:162-212, src/routes/agents.test.ts:133-154

Data Persistence

Permissions are stored across multiple relational tables to maintain normalization.

Sources: src/routes/agents.tsx:94-110, src/routes/agents.tsx:192-205

OAuth Authorization UI

For external agents (like ChatGPT or OpenAI Codex), the system provides an OAuth-compliant authorization screen. This UI allows the administrator to review and approve connection requests from external tools.

Authorization Workflow

1. Request: The external agent redirects the user to /authorize with standard OAuth parameters.
2. Review: The UI displays the agent's name and a list of all active email accounts.
3. Approval: The user selects which accounts to share and clicks "Allow Access".
4. Redirection: The system updates the agent's metadata and redirects back to the agent with an authorization code.

Sources: src/routes/authorize.tsx:81-175, src/routes/mcp-auth.test.ts:468-510

The flowchart describes the user journey through the OAuth consent screen.
Sources: src/routes/authorize.tsx:177-268, src/routes/mcp-auth.test.ts:512-553

Technical Implementation Details

Validation Logic

The system enforces several constraints to maintain security and data integrity:

• Name Length: Agent names are limited to 100 characters.
• Batch Operations: Updates to agent names and multiple permission tables occur within a single D1 transaction (db.batch) to prevent partial updates.
• Account Verification: The validateAccountSelections function checks that all submitted IDs exist in the email_accounts table before proceeding with updates.

Sources: src/routes/agents.tsx:21, src/routes/agents.tsx:85-92, src/routes/agents.test.ts:108-114

Security Controls

• CSRF Protection: All mutation routes (e.g., /agents/*, /settings/*) are protected by Hono's CSRF middleware.
• Sensitive Data Masking: In the Settings UI, credentials like Client IDs are masked (e.g., first 12 characters followed by dots) to prevent accidental exposure.
• Secret Handling: The raw client_secret is only displayed once immediately after agent creation and is never stored in plain text.

Sources: src/app.ts:45-52, src/routes/settings.tsx:21-36, src/routes/agents.tsx:135-146

Summary

The Agent Configuration UI serves as the administrative control plane for e-zer0. By providing clear separation between email and calendar permissions, enforcing strict validation, and leveraging secure Cloudflare Workers primitives, it enables safe delegation of inbox management to AI agents. The use of Hono JSX for SSR ensures the interface remains fast and accessible without requiring complex client-side frameworks.

Sources: AGENTS.md:1-20, README.md:200-220