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.

Every call is tied to one workspace. A remote client either signs in through maxclicks, where you choose the workspace and what the assistant may do, or carries an API key created in that workspace. See Authentication.

Current API coverage

The tools use the Public API for customer records, events, prepared campaigns, workflows, and webhooks. Follow each operation’s response and status fields: an accepted request can still require event readiness checks, deletion polling, or delivery tracking.

Run it

Connect a remote client to the hosted server, or run the npm package on your own machine. Remote clients can sign in; the local stdio transport uses an API key.

Local (stdio)

Requires Node.js 18 or later. Add the server to your MCP client and supply the workspace key in its environment:

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

MAXCLICKS_API_KEY is required in stdio mode. The server exits if it is unset. Keep the client configuration containing your key out of version control.

Remote (HTTP)

Connect your client to https://mcp.maxclicks.ai/mcp. A client that supports MCP authorization signs in on its own: the server answers its first request with 401 and names the maxclicks authorization server, the client identifies itself with its metadata document or by registering, and your browser opens maxclicks so you can approve the connection.

claude mcp add --transport http maxclicks https://mcp.maxclicks.ai/mcp

In Claude Code, run /mcp, select the server and authenticate. Clients configured with JSON take the URL alone:

{
  "mcpServers": {
    "maxclicks": { "url": "https://mcp.maxclicks.ai/mcp" }
  }
}

A client that cannot sign in can send a workspace API key instead, as Authorization: Bearer YOUR_API_KEY.

To run your own server with HTTP transport:

npx -y maxclicks-mcp --http --host 127.0.0.1

The local endpoint is http://127.0.0.1:7004/mcp. Override the port with PORT or --port, use MAXCLICKS_BASE_URL to select a non-default API host, and set MCP_PUBLIC_URL to the address clients use, since an OAuth token is issued for that exact address.

Verify a successful whoami response to confirm the connected workspace before making a write.

Approve a connection

When a client signs in, maxclicks shows a consent page in your browser. Sign in first if you are not already.

• The page names the app as it describes itself and marks it Not verified: any app can claim any name. An app identified by its metadata document also shows Details from with the site that published it. The page also shows where it returns you, a website's host, an app running on your computer, or an app installed on your device. Approve only a connection you started from that app just now.
• Choose one workspace. Connecting requires the Write permission in it, as creating an API key does.
• Choose what the app may do. Read, Write and Admin are offered only where the app asked for them and you hold them. Admin manages suppressions; assistants ask for Read and Write unless they need more.
• Click Allow access, or Deny. After allowing, your browser returns to the app, which finishes connecting on its own.

The connection is listed under Settings, then Developers, on the API keys tab, with the app's name and a code such as OAuth · claude.ai. Delete it there to disconnect the app at once. A connection acts as you in its one workspace, limited to what you granted and to your current role. To use another workspace, connect again and choose it.

The app holds an access token valid for one hour and renews it with a refresh token. A connection left unused for 30 days expires, and the app asks you to sign in again.

Authentication

The HTTP transport authenticates every request, including requests inside an open session. It reads the credential from, in order:

1. The Authorization: Bearer <token> header: an OAuth access token issued for this server, or an API key.
2. The X-Maxclicks-API-Key header: an API key.

A credential in the URL is not accepted. A missing or invalid credential returns 401 with a challenge that tells an OAuth client where to sign in:

WWW-Authenticate: Bearer resource_metadata="https://mcp.maxclicks.ai/.well-known/oauth-protected-resource/mcp", scope="read write"

An access token issued for the Public API rather than this server is refused with error="invalid_token". A session stays bound to the credential that opened it: another credential cannot use it, and the client's refreshed token continues the same session. The server checks a credential with a me() call and remembers the result for up to a minute, never past the token's expiry.

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

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.

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.

Related

• Authentication: API keys, and how an app connects with OAuth.
• Node SDK: the maxclicks client this server is built on.
• Public API: the endpoints every tool maps to.