Connect Mailphantom to Codex or Claude Code

The Mailphantom MCP server lets your AI assistant create and manage your phantoms from a conversation. A phantom is an email alias that forwards messages to your inbox. You can ask your assistant to create one for a new signup, find an existing address, or pause forwarding.

MCP stands for Model Context Protocol. It connects your assistant to Mailphantom's tools. Mailphantom hosts the server; you connect it with a URL and sign in through your browser.

Before you start

You need:

• A Mailphantom account with a verified email address and access through a Pro or Teams subscription.
• Codex or Claude Code installed and working on your computer. The commands below use their command-line tools.

If you are new to Mailphantom, follow the getting started guide first.

Use these connection details:

Setting	Value
Name	mailphantom
Server URL	https://mailphantom.io/mcp
Transport	Streamable HTTP
Authentication	OAuth, using your Mailphantom account

You do not need to generate an API key or install a local MCP server.

Add Mailphantom to Codex

1. Open a terminal and add the server:

   codex mcp add mailphantom --url https://mailphantom.io/mcp

2. Follow the browser sign-in if it opens. Sign in to Mailphantom, check the account and permissions shown, then select Authorize. If sign-in did not start, run:

   codex mcp login mailphantom

3. Check that the server was added:

   codex mcp list

   The list should include mailphantom. This confirms the configuration; the prompt below checks that Codex can use the connection.

4. Start a new Codex session and ask:

   Use Mailphantom to list the domains available for creating a phantom.

   Codex should use list_domains and return your available domains.

Codex stores this connection in ~/.codex/config.toml. Its local clients share the configuration on the same host, including the CLI and IDE extension. Restart an existing session if it does not show the new server.

Add Mailphantom to Claude Code

1. Open a terminal and add the server:

   claude mcp add --transport http --scope user mailphantom https://mailphantom.io/mcp

   --scope user makes the connection available across your projects. For a connection available only to you in the current project, use --scope local instead.

2. Start a new Claude Code session:

   claude

3. Enter /mcp, select mailphantom, and follow the authentication option. Sign in to Mailphantom in the browser, check the account and permissions, then select Authorize.

4. Return to Claude Code and open /mcp again to check the connection. Then ask:

   Use Mailphantom to list the domains available for creating a phantom.

   Claude should use list_domains and return your available domains.

Try it with a signup

Once connected, use ordinary requests to manage your phantoms. These examples work with either assistant.

Create an address

Use Mailphantom to create a phantom called Skylark Notes for
https://skylark.example. Check for an existing phantom for that URL first.
If I need a new one, show me the available domains and let me choose.
Return the phantom's email address.

Skylark Notes and its URL are examples. Replace them with the service you want to use. Your assistant can find existing phantoms, list your domains, and create an alias using your chosen domain. Mailphantom generates the address; the label does not become the email address.

Copy the returned address into the website's email field. Incoming emails will be forwarded to your usual inbox.

Find an existing address

Find my Skylark Notes phantom in Mailphantom. Show its email address and
whether forwarding is active.

Pause and resume forwarding

Find my Skylark Notes phantom and turn off forwarding. Keep the phantom
so I can enable it again later.

To receive emails again, ask your assistant to turn forwarding back on for the same phantom.

What the connection can access

Authorizing the connection lets your assistant list available domains and create, search, view, update, and permanently delete your phantoms. It can see phantom details such as delivery counts and the latest sender and subject. Mailphantom does not store email bodies, so the assistant cannot read your inbox or retrieve messages through this connection.

Pausing forwarding is reversible. Deleting a phantom is permanent, stops forwarding, and makes its address unavailable for reuse.

Troubleshooting

The server is listed, but tools do not work

In Codex, run codex mcp login mailphantom to sign in again. In Claude Code, use /mcp to check the server and authenticate. Confirm that you authorized the Mailphantom account you want to use, then try the list-domains prompt again.

Mailphantom reports that access is denied

Check that your email address is verified and that your current team has an active Pro or Teams subscription. Basic and trial access do not include MCP. If your Teams subscription has too few seats for its members, ask the team owner to update it.

Your assistant cannot find a phantom

Ask it to search by the phantom's label, email address, or saved website URL. Updates and details use the exact email address returned by the search. Check that you connected the Mailphantom account that owns it.

Remove the connection

For Codex:

codex mcp logout mailphantom
codex mcp remove mailphantom

For the Claude Code user connection added above:

claude mcp remove --scope user mailphantom

Use --scope local if you added it with local scope. Removing the connection leaves your phantoms in Mailphantom.

Client documentation

For more configuration options, see the official Codex MCP documentation and Claude Code MCP documentation.