MCP server

Give an MCP-compatible assistant the tools to work with your maxclicks customer data, events, and prepared campaigns. The server wraps the Public API; its actions use the same workspace permissions and limits as your own integration.

Tools call https://api.maxclicks.ai/v1. Every call carries an API key, which ties it to one space. Create a key in the app under a space's Settings, in Developers. See Authentication.

Current API coverage

The documented tool surface follows the existing SDK source. It does not yet expose the new event identity, event readiness, record deletion polling, or workflow history cursor operations. Older tool results also use earlier event and deletion types. Use the current REST reference for those flows and read the client compatibility table before automating writes. Tool success alone does not establish event readiness, finished erasure, or downstream delivery.

Run it

The server runs over stdio by default. Pass --http (or set TRANSPORT=http) to run the Streamable HTTP server instead.

maxclicks-mcp is not published to npm, so every npx -y maxclicks-mcp command on this page fails to resolve. The stdio and self-hosted configurations below require a built copy of the server. Use the hosted endpoint, which needs no install.

Local (stdio)

Point a stdio client at npx -y maxclicks-mcp and supply your key as MAXCLICKS_API_KEY. For Claude Desktop:

{
  "mcpServers": {
    "maxclicks": {
      "command": "npx",
      "args": ["-y", "maxclicks-mcp"],
      "env": { "MAXCLICKS_API_KEY": "max_..." }
    }
  }
}

MAXCLICKS_API_KEY is required in stdio mode. The server exits if it is unset.

Remote (HTTP)

Connect an HTTP client to the hosted endpoint https://mcp.maxclicks.ai/mcp. Send your key as a bearer token:

Authorization: Bearer max_...

To self-host the HTTP transport, run npx -y maxclicks-mcp --http. It listens on port 7004 by default (override with PORT). Set MAXCLICKS_BASE_URL to point at a non-default API host.

Authentication

The HTTP transport resolves the API key from the request in this order, using the first that is present:

A leading URL path segment: POST /{key}/mcp.
The Authorization: Bearer <key> header.
The X-Maxclicks-API-Key header.

The stdio transport reads the key from the MAXCLICKS_API_KEY environment variable only.

The first time the server sees a key it checks it with a me() call, then remembers the result for five minutes. An invalid key is rejected before any tool runs.

Suppression tools require an admin-scoped key. Use whoami to confirm which space and permissions a key resolves to.

Tools

Tools are grouped by resource. The read tools (list_*, get_*, count_*, whoami) never change anything. The rest map to the Public API's create, update, delete, and action endpoints.

The split follows the API itself: you build things in the app, and the tools trigger, read, and measure them. Schemas, attributes, templates, sending domains, senders, and topics are created and edited in the app, so their tools here are read-only. A broadcast is drafted and its email written in the app too, but update_broadcast can still rename one, point its audience at a different segment or at every contact in its schema, and change when it goes out.

Group	Tools
Meta	`whoami`
Schemas	`list_schemas`, `get_schema`
Attributes	`list_attributes`
Records	`list_records`, `get_record`, `create_record`, `upsert_record`, `update_record`, `delete_record`, `get_contact_audit_trail`
Events	`fire_event`, `fire_events_batch`, `list_events`
Templates	`list_templates`, `get_template`, `send_template`
Broadcasts	`list_broadcasts`, `get_broadcast`, `update_broadcast`, `send_broadcast`, `list_broadcast_runs`, `get_broadcast_metrics`
Segments	`list_segments`, `get_segment`, `create_segment`, `delete_segment`, `count_segment`, `list_segment_contacts`
Topics	`list_topics`, `get_topic`
Senders	`list_senders`
Domains	`list_domains`, `get_domain`
Suppressions	`list_suppressions`, `create_suppression`, `delete_suppression`, `batch_create_suppressions`, `batch_delete_suppressions`
Webhooks	`list_webhooks`, `get_webhook`, `create_webhook`, `update_webhook`, `delete_webhook`, `rotate_webhook_secret`
Workflows	`list_workflows`, `get_workflow`, `pause_workflow`, `unpause_workflow`, `trigger_workflow`, `list_workflow_runs`, `get_workflow_run`

Discover, then write

Start with list_schemas and list_attributes so the agent learns how your data is shaped, then read and write records. Every record tool takes a schema id or slug, and acts on the contacts or objects in that schema.

Name
upsert_record
Type
tool
Description
Create or update by the schema's identity rules. An explicit id selects one record; otherwise userId takes priority, email matches only without userId, and phone matches only without userId or email. Preserve your identity strategy and inspect warnings.
Name
fire_events_batch
Type
tool
Description
Accept up to 500 events in one schema. Matching eventId and normalized input replay the original receipt; changed input conflicts. Inspect every batch result and poll readiness through REST, because the current tool does not expose that endpoint.
Name
send_template
Type
tool
Description
Send a template to a contact, passing in the information that template asks for.
Name
trigger_workflow
Type
tool
Description
Start a run of a workflow that has an incoming-webhook trigger.
Name
create_segment
Type
tool
Description
Build a segment from a plain description of the audience. maxclicks writes the filter and stores it.
Name
send_broadcast
Type
tool
Description
Send or schedule a broadcast that was drafted in the app, then read list_broadcast_runs and get_broadcast_metrics to measure it.

Authentication: how the key the server carries is created and scoped.
Node SDK: the maxclicks client this server is built on.
Public API: the endpoints every tool maps to.