MCP server

Warmbly speaks the Model Context Protocol. Point any MCP client at Warmbly's server and it can search contacts, check campaigns, read your inbox, draft replies, and create draft campaigns and automations, all scoped to what you grant it.

• URL: https://api.warmbly.com/v1/mcp
• Transport: streamable HTTP
• Auth: an OAuth 2.1 access token (browser sign-in) or a static API key (bearer header).

There are two ways to connect. OAuth is the one-command path: you run a single add command, approve access in the browser, and the client holds a short-lived token it can refresh. An API key is the static path: you mint a key and paste it into the client config. Both reach the exact same tools, gated the exact same way.

Connect with OAuth

This is the recommended path. You do not paste a key anywhere: the client discovers Warmbly's authorization server, opens a browser for you to sign in and approve the scopes, and stores the resulting token itself.

Claude Code

claude mcp add --transport http warmbly https://api.warmbly.com/v1/mcp

Then run /mcp inside Claude Code and pick Authenticate. A browser opens, you sign in to Warmbly, approve the requested scopes, and you are connected. No header, no key.

Claude Desktop and Cursor

Add the server with just its URL, and the client runs the OAuth flow on first use:

{
  "mcpServers": {
    "warmbly": { "type": "http", "url": "https://api.warmbly.com/v1/mcp" }
  }
}

Connect with an API key

Prefer a static, long-lived credential (CI, a shared script, a client that does not implement OAuth)? Mint an API key and send it as a bearer token:

Authorization: Bearer wmbly_...

Claude Code

claude mcp add --transport http warmbly https://api.warmbly.com/v1/mcp \
  --header "Authorization: Bearer wmbly_..."

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "warmbly": {
      "type": "http",
      "url": "https://api.warmbly.com/v1/mcp",
      "headers": { "Authorization": "Bearer wmbly_..." }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "warmbly": {
      "url": "https://api.warmbly.com/v1/mcp",
      "headers": { "Authorization": "Bearer wmbly_..." }
    }
  }
}

What is exposed

The server exposes exactly the tools your credential is allowed to use, whether that credential is an OAuth token or an API key. A credential with only read scopes sees only the read tools; one with write scopes sees those too, so an MCP client acts with precisely the permissions you granted, and nothing more.

This is a subset of what the in-product assistant can do. Two categories are dashboard-only and never reachable by an API key or OAuth token: sending email (send_reply, compose_email), and workspace governance (team, workspace settings, and billing). Those routes are session-only and have no API scope to grant, so they never appear over MCP.

Every tool is gated by its API permission. tools/list returns only the tools your mask allows. Sending-class tools (anything that transmits a message to a recipient) are never exposed over MCP regardless of scope; over MCP the assistant only produces drafts (draft_reply).

Rate limits apply to MCP calls exactly as they do to the rest of the API (per-key for API keys, per-user for OAuth tokens). SEND_CAMPAIGNS appears in the table because set_campaign_status needs it, but that tool is still withheld from MCP: no send-class tool is ever exposed over the MCP transport regardless of scope.

How OAuth discovery works

The one-command flow is standard MCP authorization, so any spec-compliant client works without Warmbly-specific setup. On a request with no valid token, /v1/mcp returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata. The client then walks:

• GET /.well-known/oauth-protected-resource: the resource and its authorization server (RFC 9728).
• GET /.well-known/oauth-authorization-server: the authorize, token, and registration endpoints (RFC 8414).
• POST /v1/oauth/register: dynamic client registration, so the client mints a public (PKCE) client_id with no manual app setup (RFC 7591).
• Authorization code with PKCE (S256) in the browser, then POST /v1/oauth/token for a short-lived access token and a rotating refresh token.

The same discovery drives Warmbly's OAuth server for any client. See the OAuth 2.1 page for the full authorization-server reference.

See also

• OAuth 2.1 for the authorization-server endpoints, scopes, and dynamic registration.
• Authentication for how API keys and OAuth tokens work.
• Permissions for the full scope list.
• To connect Warmbly to external MCP servers instead (the other direction), see the Connect MCP tools guide.