snailMCP

Call tools by email.

snailMCP is a small Cloudflare Worker that receives email. It gives an AI agent that can only send email, such as Instinct, a way to call tools. The agent attaches JSON files to an email and gets the results back as files in a reply.

It costs nothing to run on Cloudflare's free plan. You only pay for a domain.

How it works

1. Your agent sends an email to your secret snailMCP address. The email has one JSON file for each tool call, and a token.txt file.

2. The Worker checks the email, then runs each call in filename order.

3. The Worker replies in the same thread. The body sums up each result, and each call file gets a .result.json file.

Each call file holds a JSON-RPC 2.0 request, the same format MCP uses:

{"jsonrpc": "2.0", "id": "1", "method": "tools/call", "params": {"name": "echo", "arguments": {"text": "hello"}}}

An email with the subject help and no files gets back a full guide and two example call files. Your agent can learn everything from that one reply.

Related MCP server: AgentMail MCP Server

What you need

• a Cloudflare account, which is free

• a domain on Cloudflare

• Node.js 20 or later on your computer

• an agent that can send email with attachments

Set it up

This takes about 15 minutes.

1. Make a Cloudflare account

Sign up at dash.cloudflare.com/sign-up.

2. Get a domain on Cloudflare

You can do one of these:

• Buy a new domain. In the Cloudflare dashboard, go to Domain Registration, then Register Domains. Cloudflare charges what the registry charges, so a cheap domain costs a few dollars a year.

• Use a domain you already have. Add it to Cloudflare and change its nameservers to the ones Cloudflare gives you.

• Use a subdomain, such as mail.example.com, of a domain already on Cloudflare.

Email Routing takes over email for the domain it runs on. If your domain already receives email somewhere else, use a subdomain.

3. Turn on Email Routing

In the dashboard, go to your domain, then Email, then Email Routing. Select Get started and let Cloudflare add the DNS records it needs.

For a subdomain, go to Email Routing settings and select Add subdomain.

Cloudflare's Email Routing guide has more detail.

4. Get the code

Select "Use this template" on GitHub, or clone the repository. Then install the packages:

npm install

5. Run the setup script

npm run setup

The script:

1. logs you in to Cloudflare, if you are not logged in already

2. asks for your domain and the email addresses allowed to call tools

3. makes your secret address and token

4. makes a Cloudflare KV namespace that remembers which emails have run

5. deploys the Worker and saves your settings as Worker secrets

It saves your token and a ready-made agent prompt in the local/ folder. Git ignores that folder.

6. Send your domain's email to the Worker

In the dashboard, go to Email Routing, then Routing rules. Edit the catch-all address, set the action to "Send to a Worker", and pick snailmcp.

Every address on your domain now reaches the Worker. The Worker rejects every address except your secret one.

7. Tell your agent

Paste local/agent-prompt.md into your agent. It holds your address, your token and how to make calls.

8. Test it

If you have just turned on Email Routing, wait 30 minutes first. Mail servers such as Gmail remember that your domain had no mail records. Until they check again, they bounce your email with "the domain couldn't be found", and the email never reaches Cloudflare.

Ask your agent to email your address with the subject help. To watch what the Worker does, run:

npx wrangler tail

Then ask your agent to send back the two example files with its token.txt.

Security

The Worker runs a call only when all of these checks pass:

1. The address. The email goes to your secret address, such as snail-7f3kq9x2ab@example.com. Mail to any other address is rejected as unknown.

2. The sender. The From address is on your allowed list, and the email passed DMARC for that address's domain. DMARC is the check that the domain really sent the email. Mail that fails is rejected as unknown, so a stranger cannot tell that the address exists.

3. The token. The email has a token.txt attachment that matches your token. If it does not match, the sender gets a reply saying so and no calls run.

These limits also apply:

• Replies only go back to the sender. Someone who forges your agent's address could start a call but would never see its result. Take more care with tools that change things than with tools that only read.

• Each email runs at most once. The Worker remembers each email's Message-ID for 7 days.

• One email can hold up to 50 call files.

• Tool results can contain text that other people wrote. The agent prompt tells your agent to treat results as information and not to follow instructions in them.

To get a new address and token, run npm run setup -- --rotate, then give your agent the new local/agent-prompt.md. The old address stops working straight away.

Before you rely on it

These things work in local tests, but only real email can confirm them:

• The DMARC check for your agent's domain. The Worker reads the DMARC result from the topmost Authentication-Results header, which Cloudflare adds. This works for email from Gmail. If wrangler tail shows your agent's email rejected with a DMARC reason, its mail service may not pass DMARC.

• Where replies go. Cloudflare sends replies to the envelope sender. Some mail services send from a separate bounce address. If your agent never sees replies, check wrangler tail for the address the reply went to.

• Your agent's sending rules. Instinct asks you to approve emails it sends from your Gmail. If your agent can send from its own address, add that address to the allowed list so calls do not wait for you.

Add your own tools

Tools live in src/tools.ts. Each tool follows the MCP tool format: a name, a description your agent reads, a JSON Schema for its arguments, and a run function. For example:

const addNote: Tool = {
  name: "add_note",
  description: "Saves a note.",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
    required: ["text"],
  },
  async run(args) {
    // Save the note somewhere, such as a KV namespace or another service's API.
    return { content: [{ type: "text", text: "Saved." }] };
  },
};

export const tools: Tool[] = [echo, now, addNote];

Then deploy:

npm run deploy

To use an API key in a tool, save it as a Worker secret with npx wrangler secret put NAME, and add it to the Env type in src/checks.ts.

Try it on your computer

You can run the Worker locally without a domain:

npm run setup -- --local
npm run dev

In a second terminal, send it test emails:

npm run try

npm run try -- help sends a help email, npm run try -- no-token leaves out the token, and npm run try -- stranger sends from an address that is not allowed. Wrangler prints where it saved each reply as an .eml file.

Run the tests with npm test.

Files

What comes next

The next version will connect to remote MCP servers, so any MCP server's tools can be called by email.