Trela Email Gateway MCP

MCP server that lets AI agents search, read, and act on a connected mailbox — every write goes through Trela's human-in-the-loop review queue instead of hitting Gmail directly.

This README covers installing and configuring the server. For the tool list, parameters, session batching, error shapes, and the direct-REST fallback, see skill/SKILL.md — the canonical tool-usage reference, shipped in the published package.

Install

Quickest: init

npx -y @trela/email-gateway-mcp init

Prompts for (or accepts as a flag) your API key — the only required setting, since the API base URL now defaults to production — verifies it against the API, and prints a ready-to-paste mcpServers block for Hermes, OpenClawd, opencode, and other MCP clients:

npx -y @trela/email-gateway-mcp init --key "$MAIL_AGENT_API_KEY"

# Pointing at a non-production deployment (e.g. staging):
npx -y @trela/email-gateway-mcp init \
  --key "$MAIL_AGENT_API_KEY" \
  --url https://staging-api.trela.app

init also reads MAIL_API_BASE_URL / MAIL_AGENT_API_KEY from the environment, and probes the API to confirm the key works unless --no-check is passed. The printed block embeds your API key — keep the resulting config file private and never commit it.

Manual: mcpServers config

{
  "mcpServers": {
    "mail": {
      "command": "npx",
      "args": ["-y", "@trela/email-gateway-mcp"],
      "env": {
        "MAIL_AGENT_API_KEY": "${MAIL_AGENT_API_KEY}"
      }
    }
  }
}

Add "MAIL_API_BASE_URL" to env only to point at a deployment other than production (e.g. https://staging-api.trela.app) — see Configuration.

Install the skill

Runtimes that discover skills from a directory (rather than an mcpServers config) need skill/SKILL.md on disk. Fetch it without a repo checkout:

npx -y @trela/email-gateway-mcp skill -o ~/.agent/skills/trela-email-gateway/SKILL.md

Or print it to stdout to pipe elsewhere: npx -y @trela/email-gateway-mcp skill.

Configuration

| Variable | Description | Required | |----------|-------------|----------| | MAIL_API_BASE_URL | Base URL of the Agent Gateway API (absolute http/https) | No — defaults to https://api.trela.app; set it only to point at a different deployment (e.g. https://staging-api.trela.app, or a local dev server) | | MAIL_AGENT_API_KEY | API key for authentication | Yes | | MAIL_REQUEST_TIMEOUT_MS | Request timeout in milliseconds (default: 10000) | No |

Never commit MAIL_AGENT_API_KEY or embed it in config files, transcripts, or tool outputs. A 401 means the key is invalid or missing — a configuration problem, not a retryable error.

opencode (this repo, dev)

For development/testing in this repository, the server is already registered in .opencode/mcp.json:

export MAIL_API_BASE_URL=http://localhost:3000
export MAIL_AGENT_API_KEY=your-api-key
opencode

Build from source

For working on the server itself, or for runtimes that need a local path instead of npx:

pnpm install
pnpm --filter @trela/email-gateway-mcp build   # bundles to dist/index.js (esbuild)

MAIL_API_BASE_URL=https://api.example.com \
MAIL_AGENT_API_KEY=your-api-key \
node packages/intents-mcp/dist/index.js

Or for development, no build step: pnpm --filter @trela/email-gateway-mcp dev (runs src/index.ts via tsx).

Development

pnpm --filter @trela/email-gateway-mcp lint
pnpm --filter @trela/email-gateway-mcp typecheck
pnpm --filter @trela/email-gateway-mcp test

Releasing

Publishing runs in CI (.github/workflows/publish-intents-mcp.yml) on tag push:

# bump "version" in package.json first, commit it, then:
git tag intents-mcp-vX.Y.Z
git push origin intents-mcp-vX.Y.Z

Architecture

• src/config.ts — configuration loading and validation
• src/schemas.ts — Zod schemas for tool input validation
• src/http.ts — HTTP client for the Agent Gateway API
• src/logger.ts — structured logging with pino
• src/errors.ts — error mapping to MCP tool results
• src/server.ts — MCP server setup and tool registration
• src/init.ts — the init subcommand
• src/skill.ts — the skill subcommand
• src/index.ts — CLI entry point / subcommand dispatch

Source of Truth

• Input validation schemas and tool behavior: src/ (this package) — if any doc conflicts with actual behavior, the source code wins.
• Tool usage, parameters, and error handling for the agent calling this server: skill/SKILL.md.