Guides

MCP

SMTP2GO MCP

https://developers.smtp2go.com/mcp is a remote Streamable HTTP MCP server. It initializes as SMTP2GO-API-Docs and exposes tools for listing/searching API endpoints plus executing API requests.

The documentation discovery tools may be available without authentication. API execution through execute-request requires an SMTP2GO API key in the X-Smtp2go-Api-Key request header.

Prefer a packaged, task-specific capability over a live tool server? See Skills.

Prerequisites

Claude Desktop connects through mcp-remote, which needs Node.js/npm installed. The first run may download mcp-remote through npx. Every other client on this page connects directly over Streamable HTTP and needs no extra tooling.

Set your API key for the current terminal session:

export SMTP2GO_API_KEY="your-smtp2go-api-key"

If your MCP client supports environment variables or a secret manager, prefer that over storing keys in project files. For local shell-driven clients, you can add the key to your shell profile, such as ~/.zshrc:

echo 'export SMTP2GO_API_KEY="your-smtp2go-api-key"' >> ~/.zshrc
source ~/.zshrc

Codex App / Codex CLI

In the Codex App, go to Settings > Configuration and open config.toml. If you use Codex CLI, the config file is usually:

~/.codex/config.toml

Add:

[mcp_servers.smtp2go]
url = "https://developers.smtp2go.com/mcp"
env_http_headers = { "X-Smtp2go-Api-Key" = "SMTP2GO_API_KEY" }
enabled = true

Codex connects directly to the remote server over Streamable HTTP. No Node.js, npx, or local bridge process is involved.

env_http_headers maps a header name to the name of an environment variable. Codex reads that variable from its own environment when it connects, so export SMTP2GO_API_KEY before starting Codex.

The Codex App may not inherit variables exported in your shell profile. If the key does not resolve there, set the header value literally instead:

[mcp_servers.smtp2go]
url = "https://developers.smtp2go.com/mcp"
http_headers = { "X-Smtp2go-Api-Key" = "your-actual-api-key" }
enabled = true

http_headers takes literal values only. It does not expand ${SMTP2GO_API_KEY}, so a value written that way is sent to the server as that exact text and authentication fails.

Claude Code

claude mcp add --transport http smtp2go https://developers.smtp2go.com/mcp \
  --header "X-Smtp2go-Api-Key: $SMTP2GO_API_KEY"

Gemini CLI

gemini mcp add smtp2go https://developers.smtp2go.com/mcp \
  --transport http \
  --header "X-Smtp2go-Api-Key: $SMTP2GO_API_KEY"

Cursor

In Cursor, go to Settings > Tools and MCPs > New MCP Server, then paste:

{
  "mcpServers": {
    "smtp2go": {
      "type": "streamable-http",
      "url": "https://developers.smtp2go.com/mcp",
      "headers": {
        "X-Smtp2go-Api-Key": "${env:SMTP2GO_API_KEY}"
      }
    }
  }
}

${env:SMTP2GO_API_KEY} is Cursor's environment-variable interpolation syntax. Cursor resolves variables in the headers field from its own process environment when it starts. Remote MCP servers cannot use Cursor's envFile setting.

On macOS, Cursor launched from Finder or the Dock may not inherit variables exported in your shell profile. If authentication fails, fully quit Cursor and launch it from a terminal where SMTP2GO_API_KEY is set. Cursor's MCP troubleshooting guide recommends confirming that shell-profile variables are available to Cursor and restarting it after environment changes.

Depending on the Cursor version, an unresolved variable may be sent literally, resolve to an empty value, or prevent the MCP connection. Check MCP Logs before using a literal key as a temporary fallback:

"headers": {
  "X-Smtp2go-Api-Key": "your-real-smtp2go-api-key"
}

A literal value stores the key in mcp.json. Remove it after testing, do not commit it, and prefer environment-variable interpolation for normal use.

Claude Desktop

Claude Desktop needs mcp-remote for this server, because its custom connectors cannot reliably send the custom X-Smtp2go-Api-Key header that SMTP2GO requires.

Open Claude Desktop, go to Settings > Developer > Edit Config, and edit claude_desktop_config.json. On macOS this file is usually:

~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "smtp2go": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://developers.smtp2go.com/mcp",
        "--header",
        "X-Smtp2go-Api-Key:${SMTP2GO_API_KEY}"
      ],
      "env": {
        "SMTP2GO_API_KEY": "your-real-smtp2go-api-key"
      }
    }
  }
}

Claude Desktop launches MCP servers directly, not through your shell, so values exported in ~/.zshrc may not be available. Put SMTP2GO_API_KEY in the server env block, then reference it with ${SMTP2GO_API_KEY} in args. The header intentionally has no space after X-Smtp2go-Api-Key: to avoid argument escaping issues in desktop MCP clients.

Save claude_desktop_config.json, then fully quit and restart Claude Desktop.

📘

Known issue with mcp-remote

After connecting, mcp-remote opens a GET request to the MCP endpoint to listen for server notifications. The endpoint currently answers with HTTP 200 and text/html instead of an event stream or 405 Method Not Allowed, so mcp-remote treats the stream as closed and reconnects about once per second for as long as the client runs. Each retry re-sends your API key.

Tools still work normally, but this produces constant background traffic. Clients on this page that connect natively over Streamable HTTP, such as Codex, Claude Code, Gemini CLI, and Cursor, are not affected.

Lovable

In Lovable, open https://lovable.dev/dashboard, then go to Connectors.

Under Chat connectors, select Custom MCP. It is usually the last item in the Chat connectors list.

Fill in the form:

  • Server name: SMTP2GO
  • Server URL: https://developers.smtp2go.com/mcp
  • Authentication: Bearer token or API key

Enter your SMTP2GO API key, then select Add server.

Lovable chat may ask for the API token again when it adds email integrations. If prompted, enter the same SMTP2GO API key.

When you ask Lovable to send email through SMTP2GO, explicitly instruct it to use a verified sender email address. Sending may fail if the sender address is not verified in your SMTP2GO account.

Confirm it works

After configuring the server, your MCP client should show these tools:

  • list-endpoints
  • get-endpoint
  • search-endpoints
  • execute-request
  • get-server-variables

Try a read-only discovery action first, such as searching for email/send or listing endpoints, before using execute-request.

Authentication Notes

Log in to SMTP2GO and create an API key at:

https://app.smtp2go.com/sending/apikeys/

These permissions are recommended for email sending:

  • /email/send
  • /allowed_senders/view
  • /domain/view

Then configure your MCP client to send the key with API execution requests as:

X-Smtp2go-Api-Key: your-smtp2go-api-key

For simplicity, most MCP client examples above send the header on every MCP request.

Do not commit real API keys to project configuration. Prefer a dedicated, narrowly scoped SMTP2GO API key for MCP use, and use environment variable expansion or a secret manager where your MCP client supports it.

execute-request can perform real SMTP2GO API actions, including sending email if the key has permission. Remove or disable the key when it is no longer needed.

Updated 5 days ago