MCP & connectors

Robotomail hosts a remote Model Context Protocol (MCP) server. Connect it to your agent, sign in to Robotomail and approve access to your mailboxes. Authentication uses OAuth; you do not need to create or paste a Robotomail API key.

https://robotomail.com/mcp

1. Create a Robotomail account and verify your email, or sign in to your existing account.
2. Open Connections and choose your agent. For clients with setup instructions, use Copy prompt and give the prompt to your agent, or follow Manual setup.
3. Approve the requested permissions in your browser, then ask your agent to list your Robotomail mailboxes.

Your existing mailbox and plan limits apply. You can use the same mailbox through MCP, the REST API and the Robotomail CLI.

In Robotomail Connections, choose Connect to Claude. This opens Claude's custom connector setup with the Robotomail server URL. Add the connector, connect your account and approve access in the Robotomail window.

You can also add a custom connector in Claude using https://robotomail.com/mcp. Choose OAuth if Claude asks for an authentication method. After connecting, enable Robotomail for your conversation. Claude Code has separate terminal instructions below.

Run these commands in your terminal, then approve access in your browser. If Robotomail is already added, run only the login command. You can also authenticate from /mcp inside Claude Code. Use the browser profile where you are signed in to Robotomail.

claude mcp add --transport http --scope user robotomail 'https://robotomail.com/mcp'
claude mcp login robotomail

Claude Code MCP documentation

Run these commands with an up-to-date Codex CLI, then approve access in your browser. If Robotomail is already added, run only the login command. Use the browser profile where you are signed in to Robotomail. In the Codex IDE extension, you can also add this URL under MCP servers and select Authenticate.

codex mcp add robotomail --url 'https://robotomail.com/mcp'
codex mcp login robotomail

Codex MCP documentation

For Cursor, merge the following robotomail entry into your MCP configuration. For Grok Bot, ask it to add a custom MCP connection with these settings. Preserve your other servers and reuse an existing Robotomail entry if you already have one.

{
  "mcpServers": {
    "robotomail": {
      "url": "https://robotomail.com/mcp",
      "auth": {
        "CLIENT_ID": "https://robotomail.com/api/mcp/clients/grok-bot",
        "scopes": [
          "mail:read",
          "mail:send",
          "offline_access"
        ]
      }
    }
  }
}

Choose Authenticate and approve access in your browser. Leave the client secret empty; this public client uses PKCE. In Grok Bot, attach Robotomail to your conversation with @.

The Robotomail Cursor plugin packages the MCP configuration with agent instructions. If you install the plugin, reuse its connection instead of adding a second server.

Run these commands where OpenClaw is installed, then approve access in your browser.

openclaw mcp set robotomail '{"url":"https://robotomail.com/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"mail:read mail:send offline_access","redirectUrl":"http://127.0.0.1:8989/oauth/callback","clientMetadataUrl":"https://robotomail.com/api/mcp/clients/openclaw"}}'
openclaw mcp login robotomail

OpenClaw MCP documentation

Run these commands in an up-to-date Hermes CLI, then sign in to Robotomail in your browser.

hermes mcp add --url 'https://robotomail.com/mcp' --auth oauth robotomail
hermes mcp login robotomail

Hermes Agent MCP documentation

On your SSH host, merge this entry into the mcp_servers section of your active Hermes profile’s config.yaml. Replace an existing robotomail entry instead of adding a duplicate. Run the login command below, open the displayed URL on any device, and approve the matching code.

mcp_servers:
  robotomail:
    url: "https://robotomail.com/mcp"
    auth: oauth
    oauth:
      flow: device
      client_id: "https://robotomail.com/api/mcp/clients/hermes-device"
      token_endpoint_auth_method: none
      scope: "mail:read mail:send offline_access"

hermes mcp login robotomail --flow device

Hermes Agent MCP documentation

The ChatGPT directory listing is coming soon. The ChatGPT button on Connections will link to the listing when it is available.

Custom MCP setup uses the same server URL, https://robotomail.com/mcp, with OAuth. Custom app creation depends on the features and permissions available in your ChatGPT account or workspace.

Start by choosing a mailbox and setting the name people will see on your emails:

List my Robotomail mailboxes and show their email addresses and display names. Ask me which mailbox to use and what sender name I want, then set that display name.

The display name applies to future sends and replies from that mailbox across all apps. It does not change the email address.

Then try a read-only request:

Find the latest received messages in that mailbox and summarize any that need a reply. Do not send anything yet.

When you want to send or reply, give your agent the intended recipient and message. Sending happens immediately. If a send times out or the result is uncertain, check the sent messages before retrying to avoid a duplicate.

The server publishes tool descriptions, input and output schemas, and permission requirements through MCP. Your client discovers them using tools/list after authentication.

• list_mailboxes (mail:read): list your mailbox IDs, email addresses and display names.
• search_messages (mail:read): list or search messages in a mailbox by text, direction or date. Returns summaries; use read_message for the body.
• read_message (mail:read): read a message's plain-text body. Large bodies can be read in parts.
• send_email (mail:send): send a plain-text email from a selected mailbox, with recipients, optional CC, subject and body.
• reply_to_email (mail:send): reply to the sender of a received message and preserve the conversation thread.
• set_mailbox_display_name (mail:send): set the friendly From name for future emails, or clear it with an empty string.

MCP currently supports plain-text mail without attachments or reply-all. Use the REST API or CLI for mailbox creation, and the REST API for HTML email, attachments, webhooks and domain management.

• mail:read allows the connected app to list and read the account's mailboxes and messages.
• mail:send allows sending, replying and changing mailbox display names.
• offline_access allows the client to refresh its authorization without a new browser approval each time.

Review the app and permissions on the consent screen. To revoke access, open Connections, find the connected app and choose Disconnect, then confirm. That app must receive a new approval before it can use your mailboxes again. Your API keys and other connected apps continue to work.

Use Streamable HTTP at https://robotomail.com/mcp with OAuth. Compatible clients can discover the authorization server from the protected resource metadata. Robotomail supports authorization code with PKCE, refresh tokens and the OAuth device authorization grant.

• Protected resource metadata: https://robotomail.com/.well-known/oauth-protected-resource/mcp
• Authorization server metadata: https://robotomail.com/.well-known/oauth-authorization-server/api/auth

The OAuth resource is https://robotomail.com/mcp. Public clients use a hosted Client ID Metadata Document (CIMD) or a client registration arranged with Robotomail. Dynamic client registration is disabled. Configure the scopes your client needs: mail:read, mail:send and offline_access.

Device login lets a remote agent display a verification URL and code while you approve in any browser. The protocol is available to compatible clients; among the setup options above, Hermes exposes this flow. Other clients use their browser-based OAuth setup.

For terminal clients, a final localhost or 127.0.0.1 callback is expected: it delivers the approval to the waiting CLI process. Keep that process running until it confirms login. On an SSH host, use device login when your client supports it.

The OpenAPI specification describes the REST API. MCP tools and their schemas are discovered from the MCP server. This guide is also available as Markdown for agents.