mailly-mcp
The MCP server behind Mailly's connector, plus the Mailly plugin for Claude and Codex.
src/: the MCP server, a Cloudflare Worker. It offers typed tools for Mailly mail, drafts, sending,
domains, contacts, templates, campaigns, workflows and webhooks. Every tool calls the
Mailly REST API with the caller's Mailly API key, so authentication, billing and
workspace isolation all stay in the API.
ui/: the MCP Apps UI (email and draft cards), bundled into ui:// resources. It is off unless
MCP_APPS=1.
plugins/mailly: the plugin for Claude (claude.ai, Cowork and Claude Code) and Codex. It
points at the hosted server and adds a skill for working with email safely.
plugins/openai/mailly: the public ChatGPT/Codex update package, based on the
published 0.3.1 release, with its existing listing, review cases, demo link, skill, and PNG icon retained.
Use the hosted server
Add https://mcp.mailly.site/mcp as a remote MCP server and sign in with your Mailly account (OAuth). In
ChatGPT, add the published Mailly plugin.
In Claude Code you can install the plugin instead:
/plugin install mailly --marketplace superagents-lab/mailly-mcp
This server is an OAuth protected resource. Mailly's API (https://api.mailly.site/api/auth) is the authorization
server: clients find it through /.well-known/oauth-protected-resource, sign the user in there, and send the
access token here. The server passes the token, or an API key, unchanged to Mailly's REST API, which checks it and
the scopes it carries. The tool list is narrowed to the same scopes (GET /me).
Keep ChatGPT and Codex connections authorized
Mailly issues a refresh token only when offline_access is granted; without it, sign-in succeeds but the
connection dies when the one-hour access token expires (ChatGPT then emails "Reconnect your plugin Mailly
for daily MCP scans"). Many clients, ChatGPT included, request exactly the scopes this server advertises, so
the 401 challenge (WWW-Authenticate: Bearer ..., scope="...") and the protected resource metadata
(scopes_supported) list offline_access next to the Mailly scopes (REQUESTED_SCOPES in src/scopes.ts).
It grants no Mailly data. The OpenAI and Codex plugin configurations
(plugins/openai/mailly/mcp.json, plugins/mailly/.codex-plugin/mcp.json) also request it in
extensions.com.openai.auth.baseScopes.
A connection made before a client could see offline_access has no refresh token: reconnect it once after
the Worker is deployed. For manually configured clients, include offline_access alongside the desired
Mailly scopes when starting OAuth authorization.
Package the contents of plugins/openai/mailly as the upload root. Do not include the repository,
marketplace, or the installed plugin's Portal-generated .app.json and apps binding in a public
upload. Keep those generated bindings in the installed release; the submission portal owns them.
The package version is 0.3.2. Separately, the Worker declares all three tool annotation booleans
explicitly, including destructiveHint: false for read-only tools; that server update requires a
Worker deployment and rescan. The MCP Registry listing is unchanged.
Run it yourself
npm install
npm run dev # wrangler dev on http://localhost:8787/mcp
Call /mcp with Authorization: Bearer <your Mailly API key> (from https://mailly.site/app/developers).
Without the MAILLY_API service binding it calls MAILLY_API_URL (default https://api.mailly.site) over
the internet. To host your own copy, change the mcp.mailly.site route in wrangler.jsonc. OAuth sign-in only
works at https://mcp.mailly.site/mcp, because Mailly issues tokens for that resource; elsewhere use an API key.
Develop
npm run typecheck
npm test # builds dist/worker.js and runs it in Miniflare against a stub API
The Mailly server repository runs its OAuth and end-to-end tests against dist/worker.js from a sibling
checkout of this repository.
server.json is the listing in the MCP Registry as
site.mailly/mcp. The site.mailly namespace is proven by a DNS TXT record on mailly.site, so publish with
mcp-publisher login dns --domain mailly.site --private-key <key> and mcp-publisher publish from a machine that
holds the key. Bump version for each release.
License
MIT