Let the agent sign itself up

You don’t need to write code or handle API keys to put an agent on MachineMail. Pick the way that fits your agent:

Each way ends with something you can see and revoke in the dashboard. See Review and revoke access.

Let the agent sign itself up

The agent registers itself, gets its own inbox and credential, and asks you to claim it. No key leaves the dashboard.

1. Copy the agent prompt

Choose Copy agent prompt. You’ll find it on the Overview page under Quick start, and in the command menu (⌘K).

Paste the prompt into your agent.

2. Wait for the code

The agent reads the instructions, registers, and gets a sandbox inbox on machinemail.dev. It then shows you a link and a 6-digit code. The code expires after 10 minutes. The agent can print a new one.

3. Claim the agent

4. Open the link the agent gave you. Or open machinemail.dev/claim and type the code. Sign in if asked.

5. Check the card. It shows the agent’s name, its Inbox, the Email it was bound to, if any, and when it Registered. The agent chose its own name, so don’t rely on it.

6. Choose Confirm and bind. Choose Cancel if this is not the agent you expect.

The agent now belongs to your organization. It keeps its inbox and gets an organization-scoped key. Within a few seconds it picks up its new credentials and carries on.

You can also start from Settings → Agent registrations → Claim an agent, or from Claim an agent in the command menu.

Note: Treat the code like a password. Unless the agent named the email address that must claim it, anyone signed in who has the code can claim the agent into their own organization. Claiming an agent has the details.

Approve an MCP app

MCP clients sign in with OAuth. You approve them in the browser once.

1. Add the server

Add https://mcp.machinemail.dev/mcp to your client with no credentials. Client setup has the exact steps for each client. The client then opens your browser.

2. Check the request

The Connect an app page asks Allow followed by the app’s name to use MachineMail? Sign in first if asked. Check:

• the app’s name. It says Name not verified unless MachineMail could check where the app comes from.
• where your browser goes back to ( Returns to).
• the list under It will be able to.

3. Choose what it can reach

Use In to pick what the app can reach: All of your organization, one pod or one inbox. Pick the narrowest option that does the job.

4. Approve

Choose Approve (or press ⌘↵). Your browser goes back to the app, which is now connected. Deny shares nothing.

The request waits 10 minutes. After that, go back to the app and connect again.

Approve the CLI

1. Start the sign-in

Run machinemail login in a terminal. It prints a code of 8 letters and a link to machinemail.dev/cli. Press Enter to open the link, which fills in the code. You can also open it on another device.

2. Check the code

The Sign in the CLI page shows the code, the machine’s name, the access ( All permissions except inbound_raw) and when it was requested. Make sure the code matches the one in your terminal.

3. Approve

Choose Approve. The dashboard creates an API key named after the machine, for example CLI on ada-mbp, and the CLI picks it up within a few seconds. Deny creates nothing. Codes expire after 10 minutes and work once.

Approve only a code you asked for yourself. CLI authentication covers profiles, CI and signing out.

Review and revoke access

Everything you connected is listed in the dashboard. Revoking takes effect at once.

Agent registrations shows each agent’s name, type, inbox, status and when it was claimed. A revoked agent gets 401 on every request. It has to register and be claimed again to come back. Its inbox and mail stay.

Connected apps shows each app, what it can reach, who approved it, when it connected and when it was last used. A disconnected app’s tokens stop working. Someone has to sign it in again to use it.

Note: A claimed agent can renew its token for about a day. For an agent that should keep working longer, give it an API key. See Create a key for an agent.

Troubleshooting