MCP Configuration

Mailisk supports the Model Context Protocol (MCP), allowing coding agents and automation tools to create test email addresses and wait for inbound messages through Mailisk.

The hosted MCP endpoint is:

https://api.mailisk.com/mcp

Requirements

To configure MCP you need:

• A Mailisk organisation on a paid plan
• Organisation owner or admin access
• An MCP API key created in the Mailisk dashboard

MCP API keys are separate from regular Mailisk REST API keys. They start with sk_mcp_ and can be scoped to specific MCP capabilities.

Create an MCP API key

1. Open MCP in the dashboard.
2. Choose the organisation you want the agent to access.
3. Click Create MCP key.
4. Choose the scopes the key should have.
5. Copy the generated secret immediately. It is only shown once.

The available scopes are:

• namespace:read: list namespaces and read namespace metadata
• email:read: search and wait for inbound emails

Most agents need both scopes so they can generate recipient addresses and wait for the matching email.

Configure Codex

For Codex, add Mailisk to ~/.codex/config.toml:

[mcp_servers.mailisk]
enabled = true
url = "https://api.mailisk.com/mcp"

[mcp_servers.mailisk.http_headers]
Authorization = "Bearer sk_mcp_YOUR_API_KEY"

Replace sk_mcp_YOUR_API_KEY with the MCP API key secret from the dashboard.

Generic MCP client config

Some MCP clients use JSON configuration. For those clients, use:

{
  "mcpServers": {
    "mailisk": {
      "url": "https://api.mailisk.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_mcp_YOUR_API_KEY"
      }
    }
  }
}

Available tools

Once configured, Mailisk exposes these MCP tools:

• create_email_address: generates a unique recipient address in an existing Mailisk namespace. Use the returned email_address in the app or test flow that sends email.
• wait_for_email: waits for an inbound email sent to the generated address. Pass the to_addr_prefix, namespace, and from_timestamp returned by create_email_address.
• get_email: fetches a known email by namespace, email_id, and received_timestamp. Use the namespace, email.id, and received_timestamp returned by wait_for_email. The response shape matches wait_for_email.

By default, wait_for_email and get_email return compact email metadata, code candidates in extracted.codes, and URL candidates in extracted.urls parsed from the plain-text body. Treat these as candidates in source order, not guaranteed answers. They do not return the full text or html body unless requested.

Typical flow:

1. Ask the agent to call create_email_address.
2. Use the returned email_address in the app or test flow that sends email.
3. Ask the agent to call wait_for_email with the returned namespace, to_addr_prefix, and from_timestamp.

Most agents should be able to automatically do these steps as needed.

The returned from_timestamp includes a small lookback from when the address was generated. This helps avoid missing emails that arrive immediately after the app action starts.

If you need the email body, pass include_text: true for the truncated plain-text body or include_html: true for the truncated HTML body. Prefer the default response for clear OTP and verification-code flows so agents avoid loading large email templates into context.

Mailisk does not send the email for you. Your app, test, or CI workflow must send the email to the generated address.

Troubleshooting

• If authentication fails, confirm the key starts with sk_mcp_ and is sent as Authorization: Bearer ....
• If the client connects but tools fail, confirm the key has both namespace:read and email:read scopes.
• If access is forbidden, confirm the selected organisation has MCP access enabled on its plan.
• If no email is found, make sure the message was sent after the from_timestamp returned by create_email_address.