What is Unspam MCP Server?

The Unspam MCP (Model Context Protocol) server lets AI agents securely access your email deliverability platform and enrich their answers with real-time spam checks, inbox placement tests, and automated monitoring data.

MCP is an open standard that allows AI tools to connect with third-party APIs in a secure, consistent way. In our case, it connects AI assistants with Unspam, enabling you to ask your AI to run spam checks, view screenshots, configure automatic tests, and check your quotas—all through natural conversation.

Unspam provides a hosted, remote MCP server. Your client connects to it over HTTPS and authenticates with your Unspam account via OAuth, meaning there is no API key to copy or paste.

MCP access is available exclusively on subscription plans that include API usage.

Most popular AI tools support connecting to the remote MCP directly. Here are the step-by-step setup guides for supported clients:

Claude Desktop
Claude Code
ChatGPT
Cursor
Windsurf
Any client implementing the MCP specification

Prerequisites

Before setting up the connection, ensure you have the following ready:

API Access: An Unspam account on a subscription plan that includes API usage.
No API Key Needed: Unspam uses modern OAuth 2.1 authentication with discovery, Dynamic Client Registration, and the Authorization Code grant with PKCE. The token must carry the mcp scope. You do not need to generate or manage API keys. Your client will open a browser for you to sign in and grant access securely.
Compatible AI Client: An MCP-compatible AI application installed and ready to configure (see the list above).

Connect to Unspam MCP

Unspam provides a hosted, remote MCP server. Use the following URL when prompted by your specific client configuration:

Connection URL

All requests are POST to a single endpoint. Protocol version: 2024-11-05. Streamable HTTP: https://api.unspam.email/mcp

Any MCP client that supports remote (HTTP/streamable) servers with OAuth can connect. The shape is always the same: point the client at the URL above, complete the OAuth sign-in when a browser opens, and the Unspam tools appear in your assistant. Clients that only support stdio servers can bridge through npx -y mcp-remote https://api.unspam.email/mcp .

Claude Desktop (Anthropic's desktop app)

Claude Desktop allows you to add custom connectors easily.

Click on your profile icon in the lower-left corner of the Claude app and choose Settings from the menu.
In the Settings, navigate to Connectors and click Add custom connector.
Name it Unspam and set the URL to https://api.unspam.email/mcp .
Click Connect. This will automatically open a browser window for you to complete the OAuth sign-in to Unspam.

Note:

If your build does not offer custom connectors in the UI, you can bridge the remote server through mcp-remote in your claude_desktop_config.json (Settings → Developer → Edit Config). It requires Node.js.

{
  "mcpServers": {
    "unspam": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.unspam.email/mcp"]
    }
  }
}

Restart Claude Desktop. A browser will open once to authorize, and the token is cached for future launches.
Enable the connector in the chat settings dropdown. Add a prompt, for example: Run a spam check and tell me when it's done, then show me the heatmap."

Claude Code (Anthropic's CLI for developers)

Claude Code uses a built-in configuration vault to manage MCP servers.

1. Add the server with the CLI using the streamable HTTP transport:

claude mcp add --transport http unspam https://api.unspam.email/mcp

(Add --scope project to the command to share the server with your team via a checked-in .mcp.json file).

Start Claude Code and type /mcp . Select unspam from the list and follow the OAuth prompt to sign in via your browser.

{
  "mcpServers": {
    "unspam": {
      "type": "http",
      "url": "https://api.unspam.email/mcp"
    }
  }
}

With the connection confirmed, you can issue natural language commands: "How much of my monthly Unspam quota is left?"

ChatGPT (OpenAI's AI Assistant)

ChatGPT supports the Model Context Protocol through Developer Mode. This is available for ChatGPT Plus, Pro, and Business plans.

Go to your profile icon and select Settings.
Navigate to Apps, then enable Developer mode.
Click Create or Add custom app.
Fill in the name (e.g., "Unspam MCP") and set the MCP server URL to https://api.unspam.email/mcp .
Choose OAuth as the authentication method. ChatGPT will automatically discover the Authorization, Token, and Registration URLs.
Save the configuration, click Connect, and sign in to Unspam in the browser to approve access.
Start a new chat, enable the app in the composer, and type a query: "Start an inbox placement test across all my mailboxes and summarize where my email landed."

Cursor (AI-Native Code Editor)

Cursor supports MCP servers to give its AI "Composer" and "Chat" features direct access to external tools.

Open your Cursor settings.
In the settings sidebar, select the MCP section.
Click to add a new MCP server. Update your configuration to use the Unspam URL:

{
  "mcpServers": {
    "unspam": {
      "type": "streamableHttp",
      "url": "https://api.unspam.email/mcp"
    }
  }
}

Confirm unspam is listed in your MCP settings.
Click Login or Needs login next to the server name to complete the OAuth flow in your browser.
Open the AI pane in Cursor and set the mode to Agent to start querying Unspam.

Windsurf (Codeium's Agentic IDE)

Windsurf supports MCP servers through its Cascade AI system using a global configuration file.

Go to the Windsurf Settings and navigate to the Cascade section.
Open your mcp_config.json file (usually located at ~/.codeium/windsurf/mcp_config.json ).
Update your configuration with the following JSON:

{
  "mcpServers": {
    "unspam": {
      "serverUrl": "https://api.unspam.email/mcp"
    }
  }
}

Save the file. Press the refresh button in the Cascade MCP panel to trigger the OAuth login and authorize the connection.

Managing Connected Apps

Because Unspam uses secure OAuth authentication, you have full control over which AI clients have access to your account. You can view or revoke access for any client at any time directly from your dashboard.

How to Manage Your Connections

Log in to your Unspam dashboard.
Click on your profile icon or email address in the top right corner.
Select API & MCP from the dropdown menu, or navigate directly to https://unspam.email/auth-tokens.
In the Connected apps section, you will see a list of external apps you’ve authorized to access your Unspam account through MCP (e.g., Claude, ChatGPT). You can revoke any connection here to cut its access immediately.

How to Revoke Access

If you no longer want an AI assistant to have access to your Unspam data, simply click the Revoke button next to its name. A confirmation pop-up will appear.

Click to confirm, and the client will instantly lose all permissions to run tests or view data on your behalf.

Available Tools & Use Cases

Once connected, the MCP server exposes multiple tools across your deliverability suite. Here are the categories and examples of how to prompt them:

1. Account Status

(Tools: get_account_status )

"How much of my monthly quota is left?"
"What is my current Unspam subscription status?"

2. Spam Checks

(Tools: start_spam_check , list_spam_checks , get_spam_check_result , get_spam_check_screenshots , get_spam_check_heatmap, create_client_preview, list_client_previews, list_client_preview_devices )

"Run a spam check and tell me when it's done."
"Show me the screenshots and heatmap for my last spam check."

3. Inbox Placement

(Tools: list_mailboxes , start_inbox_placement_test , list_inbox_placement_tests , get_inbox_placement_result )

"Start an inbox placement test across all my mailboxes and summarize where my email landed."
"Re-run that test against only Gmail and Outlook mailboxes."

4. Automatic Testing (Senders)

(Tools: create_scheduled_test_sender , list_scheduled_test_senders, get_scheduled_test_sender , update_scheduled_test_sender , delete_scheduled_test_sender , test_scheduled_test_sender_connection )

"Set up a weekly automatic test using my SMTP sender and email me if anything hits spam."
"Trigger my newsletter automatic test now and show the latest run's results."

5. Automatic Testing (Tests & Runs)

(Tools: create_scheduled_test , set_scheduled_test_email, get_scheduled_test , list_scheduled_tests, configure_scheduled_test , set_scheduled_test_status , dispatch_scheduled_test, delete_scheduled_test, list_scheduled_test_runs, get_scheduled_test_run )

insert sample here

Troubleshooting & Testing

Protocol Basics

If you are integrating directly rather than through a client, the server implements three JSON-RPC methods. The MCP server speaks JSON-RPC 2.0 over HTTP.

1. `initialize`

Performs the initial handshake. Returns the protocol version and server info.

curl -X POST https://api.unspam.email/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize" }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "unspam", "version": "1.0.0" }
  }
}

2. `tools/list`

Returns the catalog of available tools, each with a JSON Schema inputSchema . This is the authoritative, machine-readable description of every tool and its parameters.

curl -X POST https://api.unspam.email/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }'

3. `tools/call`

Invokes a tool by name with arguments . The result payload is a JSON document returned as text content.

curl -X POST https://api.unspam.email/mcp \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_spam_check_result",
      "arguments": { "id": "abc123" }
    }
  }'