Skip to main content
Glama
Cresca MCP Server

Cresca MCP Server

Cresca MCP server

Send transactional email, check delivery, manage email templates and add contacts from your AI assistant.

This is a Model Context Protocol (MCP) server for the Cresca email API. Connect it to Claude Code, Claude Desktop, Cursor or any other MCP client, and you can ask in plain words:

Send a test of the password-reset template to me@acme.com with NAME set to Ana.

Did the order confirmation we sent to sam@example.com an hour ago get delivered?

Create a draft template called "trial-ending" with a subject and a short HTML body, then show it to me before publishing.

Add these 40 beta testers to a contact list called "Beta".

The server runs on your own machine over stdio and calls Cresca's public REST API at https://api.cresca.xyz/api/v1 with your API key. Your key stays in your local environment and is only ever sent to that API.

Sending is real. send_email and send_batch_emails send real email to real people, and a sent email cannot be recalled (only a scheduled or still-queued one can be canceled). The tools tell the assistant to confirm the recipients and content with you first, and they are marked destructive so MCP clients ask before running them. Read what the assistant is about to send before you approve it.

Contents

Related MCP server: agentisend

What you can do

Task

Tools

Send one email, or up to 100 different emails in one request

send_email, send_batch_emails

Check whether an email was delivered, bounced or is still queued

get_email, list_emails

Reschedule or cancel an email that has not gone out yet

update_scheduled_email, cancel_email

Draft, review, publish and delete email templates with {{{VARIABLES}}}

create_template, get_template, list_templates, update_template, publish_template, delete_template

Add people to a marketing contact list

add_contacts

Requirements

  • Node.js 18 or newer

  • A Cresca account with a verified sending domain and an active sender. The quickstart covers both.

  • An API key from app.cresca.xyz/api-keys:

    • Sending access keys can only use send_email and send_batch_emails. Every other tool returns 401 restricted_api_key.

    • Full access keys can use every tool.

New to Cresca? You can start free for 30 days, no credit card required.

Install

There is nothing to install by hand. The server is published on npm as @crescadotxyz/mcp, and the client configurations below start it with npx -y @crescadotxyz/mcp, which downloads it the first time and reuses it after that.

To run it from source instead:

git clone https://github.com/lalitkumarjangid/cresca-mcp.git
cd cresca-mcp
npm install
npm test        # optional: runs the test suite against a mocked API

Then replace npx -y @crescadotxyz/mcp in the snippets below with node /absolute/path/to/cresca-mcp/src/index.js.

A hosted (remote) version that needs no local install is planned.

Connect your MCP client

Variable

Required

Default

Meaning

CRESCA_API_KEY

yes

Your API key (cr_live_...). Sent only as Authorization: Bearer ... and never logged.

CRESCA_API_URL

no

https://api.cresca.xyz/api/v1

Base URL including /api/v1. Must be https (plain http is allowed only for localhost).

The server starts without a key, so your client can list the tools, but every tool call fails with a clear message until CRESCA_API_KEY is set.

In the snippets below, replace cr_live_... with your key.

Claude Code

claude mcp add --transport stdio --env CRESCA_API_KEY=cr_live_... cresca \
  -- npx -y @crescadotxyz/mcp

Add --scope user to make it available in every project. Check it with claude mcp list, or /mcp inside a session.

Claude Desktop

Open Settings, then Developer, then Edit Config. On macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json. Add the server and restart Claude Desktop:

{
  "mcpServers": {
    "cresca": {
      "command": "npx",
      "args": ["-y", "@crescadotxyz/mcp"],
      "env": {
        "CRESCA_API_KEY": "cr_live_..."
      }
    }
  }
}

If Claude Desktop cannot find npx (common with nvm), set "command" to the full path that which npx prints.

Cursor

Add the same block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "cresca": {
      "command": "npx",
      "args": ["-y", "@crescadotxyz/mcp"],
      "env": {
        "CRESCA_API_KEY": "cr_live_..."
      }
    }
  }
}

Other MCP clients

Any client that can start a stdio server works: the command is npx -y @crescadotxyz/mcp with CRESCA_API_KEY in its environment.

Keep your key out of any configuration file you commit to a repository.

Tools

Tool

Endpoint

What it does

Key

send_email

POST /emails

Sends one email to up to 50 recipients, with HTML/text or a published template, attachments, tags, headers, scheduling

sending or full

send_batch_emails

POST /emails/batch

Sends 1 to 100 different emails in one all-or-nothing request

sending or full

get_email

GET /emails/:id

Retrieves one email and its latest status (last_event)

full

list_emails

GET /emails

Lists API emails, newest first, with cursor pagination

full

update_scheduled_email

PATCH /emails/:id

Changes the send time of a scheduled email

full

cancel_email

POST /emails/:id/cancel

Cancels a scheduled or queued email

full

create_template

POST /templates

Creates a template draft

full

list_templates

GET /templates

Lists templates, newest first

full

get_template

GET /templates/:id

Retrieves a template by id or alias

full

update_template

PATCH /templates/:id

Changes a template draft (live email keeps the published version)

full

publish_template

POST /templates/:id/publish

Publishes the draft as the new live version

full

delete_template

DELETE /templates/:id

Permanently deletes a template

full

add_contacts

POST /contacts

Adds 1 to 1,000 contacts to a marketing list (creates the list if needed)

full

Annotations: the four get_/list_ tools are readOnlyHint: true. send_email, send_batch_emails, cancel_email, update_template, publish_template and delete_template are destructiveHint: true. Sending is additive in MCP terms, but it is irreversible and reaches real people, so it is marked destructive on purpose.

Idempotency

idempotency_key is required on send_email and send_batch_emails (1 to 256 characters), and it's sent as the Idempotency-Key header. Build it from the real-world event the email is about, for example order-confirmation/1042 or password-reset/<reset request id>, and reuse it on every retry. The server never generates one: a random key per call would let an assistant that calls the tool twice send two emails.

  • Same key and body within 24 hours: the original result comes back (idempotent_replayed: true) and nothing is sent.

  • Same key with a different body (usually rewritten content on a retry): the tool returns already_sent: true with a note that the task is complete. It is deliberately not an error, so the assistant doesn't re-plan and resend under a new key.

  • Same key while the first request is still running (409 concurrent_idempotent_requests): retried with the same key.

  • Keys last 24 hours. If work can resume after that (queues, long-running agents), keep your own record of what was sent.

Errors and retries

API errors come back as tool errors in the form Cresca API error <status> <name>: <message>, for example Cresca API error 403 invalid_from_address: .... A 429 also includes Retry after N seconds. See www.cresca.xyz/docs/errors for every name.

Only requests that are safe to repeat are retried (up to 2 times, on network errors, 429 rate_limit_exceeded, 409 concurrent_idempotent_requests and 5xx): GET requests, and sends that carry their idempotency key. monthly_quota_exceeded is never retried. Other writes (cancel, publish, delete, create/update template, add contacts) are sent exactly once.

Inputs that the API would reject anyway (more than 50 recipients, html combined with a template, an empty batch, after and before together, and so on) are refused locally before any request is made.

Limits

These follow the Cresca API docs, and the tool schemas enforce them:

Limit

Value

Recipients per email (to + cc + bcc)

50

Emails per batch request

100 (no attachments or scheduled_at in batches)

Attachments per email

20, up to 7 MB in total, base64 only

Tags per email

10, ASCII letters, numbers, _ and -, up to 256 characters

Custom headers per email

50

Subject

998 characters, single line

Scheduling

up to 30 days ahead; a past time sends immediately

Request body

10 MB

Idempotency key

1 to 256 characters, kept 24 hours

Template name / alias / preview text

120 / 64 / 500 characters

Template variables

50 per template; string values up to 2,000 characters

Contacts per request

1,000; 120 requests per 15 minutes

List page size

1 to 100, default 20

Email retention

30 days

Requests per second depend on the plan (Free 2, Professional 10, Premium 20, Ultra 50, Enterprise 100) and are shared by all of an account's keys. API email uses the same monthly allowance as campaigns; each recipient counts as one email.

Not supported

Cresca does not offer these, so there are no tools for them:

  • Outbound webhooks (poll get_email / list_emails for status instead)

  • SMTP relay

  • Official SDKs (this server calls the REST API directly)

  • Attachments by URL (path): send base64 content

  • Open and click tracking for API email

The API is for transactional email (password resets, receipts, alerts). Newsletters and promotions belong in Cresca campaigns, which add the unsubscribe link marketing email needs.

Security

  • Your key never leaves your machine except to the Cresca API. It is read from the environment, sent only in the Authorization header to CRESCA_API_URL, never logged, and kept off the client object so it cannot appear if the object is printed.

  • No plain-text key transport. The base URL must use https; plain http is accepted only for localhost during development.

  • Use the narrowest key. If the assistant only needs to send, give it a Sending access key. It cannot read your email history or change templates.

  • Nothing is sent without you. Send, cancel, publish and delete tools are marked destructive, so MCP clients ask for approval before running them.

  • Requests time out. A request that gets no answer is abandoned after 30 seconds instead of hanging the tool call.

  • Never commit a key. This repository's .gitignore excludes .env files and other secret files. If a key is ever exposed, delete it at app.cresca.xyz/api-keys and create a new one.

Found a security problem? Email lalit@cresca.xyz rather than opening a public issue.

Troubleshooting

You see

What it means

Fix

CRESCA_API_KEY is not set

The client started the server without the key

Add CRESCA_API_KEY to the server's env block and restart the client

401 restricted_api_key

A Sending access key was used for a tool that reads or changes data

Use a Full access key for that tool

403 invalid_from_address

The from address is not an active sender on a verified domain

Verify the domain and add the sender in Sending Domains

422 validation_error on a template send

The template is not published, or a required variable is missing

Publish the template, or pass every variable without a fallback

429 rate_limit_exceeded

Too many requests per second for your plan

The server retries safe requests; otherwise wait and try again

429 monthly_quota_exceeded

The plan's monthly email allowance is used up

Upgrade the plan or wait for the next period

The client cannot start the server

npx or node is not on the client's PATH

Use the full path to npx in "command" (which npx prints it)

Every error name is listed at www.cresca.xyz/docs/errors.

Development

src/index.js    stdio entry point
src/server.js   MCP server: registers tools, formats results and errors
src/tools.js    one tool per endpoint: schemas, descriptions, annotations
src/client.js   HTTP client: auth header, idempotency, retries, errors
test/           node:test suites with a mocked fetch, plus a stdio smoke test

npm test never calls the real Cresca API: the tool tests use a mocked fetch, and the smoke test starts the server over stdio against a local mock HTTP server.

License

MIT. See LICENSE.

Available Tools

13 tools
add_contactsAdd contacts to a listA
Idempotent

POST /contacts. Adds 1 to 1,000 contacts to a marketing contact list, creating the list if it does not exist. Existing contacts get their name updated and are added to the list; nobody is duplicated. Invalid, disposable, role/no-reply, suppressed and duplicate addresses are rejected and listed in errors (with their index); the rest are still added. When the plan's contact limit is reached, summary.limit_reached is true. Imports are limited to 120 requests per 15 minutes. Only add people who agreed to receive marketing email. Needs a full-access key. Does not send any email.

Inputs: contacts (required), list_name (required).

cancel_emailCancel scheduled emailA
Destructive

POST /emails/:id/cancel. Cancels an email that is still "scheduled" or "queued" so it is never sent; this cannot be undone (send it again to deliver it). Once sending has started it can no longer be canceled and the API returns 422 validation_error. A canceled email does not count toward the monthly allowance. Needs a full-access key.

Inputs: id (required).

create_templateCreate templateA

POST /templates. Creates a template DRAFT (it cannot be sent until publish_template is called). Use {{{VARIABLE}}} placeholders in html, text, subject and preview_text. The template also appears under Transactional > Templates in the Cresca app. Needs a full-access key. Returns { object: "template", id }.

Inputs: html (required), name (required), from, text, +5 more.

delete_templateDelete template (permanent)A
DestructiveIdempotent

DELETE /templates/:id. PERMANENTLY deletes a template, by id or alias, and its version history, from the API and the Cresca app. This cannot be undone. Emails that still reference it fail with 404 not_found, so confirm with the user first. Needs a full-access key.

Inputs: id (required).

get_emailRetrieve emailA
Read-onlyIdempotent

GET /emails/:id. Returns one email sent through the API: from, to, cc, bcc, reply_to, subject, html, text, created_at, scheduled_at, tags and its latest status as last_event (queued, scheduled, sending, sent, delivered, delivery_delayed, bounced, complained, failed, suppressed or canceled). "delivered" means the receiving server accepted it, not that it reached the inbox. Emails are kept for 30 days. Needs a full-access key. Read-only.

Inputs: id (required).

get_templateRetrieve templateA
Read-onlyIdempotent

GET /templates/:id. Returns a template by id or alias. html, subject and the other content fields show the current DRAFT; status is "draft" until the first publish, then "published"; version is the published version that sends use. Needs a full-access key. Read-only.

Inputs: id (required).

list_emailsList emailsA
Read-onlyIdempotent

GET /emails. Lists emails sent through the API, newest first, without html/text bodies (use get_email for those). Cursor pagination: while has_more is true, pass the id of the last item as after for the next page, or the first item's id as before for the previous page. Use after or before, not both. Emails are kept for 30 days. Needs a full-access key. Read-only.

Inputs: after, limit, before.

list_templatesList templatesA
Read-onlyIdempotent

GET /templates. Lists every template in the account, newest first, including drafts and templates not set up for the API (status "draft", alias null). Content fields show the current draft; version is the published version sends use. Pagination: while has_more is true, pass the last item's id as after. Needs a full-access key. Read-only.

Inputs: after, limit.

publish_templatePublish template (changes live email)A
Destructive

POST /templates/:id/publish. Copies the current draft (HTML, text, subject, default sender, Reply-To, preview text and variables) into a new published version. EVERY email sent with this template from then on uses the new version, so confirm with the user before publishing a template that is in use. Undeclared placeholders are added as string variables without a fallback. Earlier versions stay in the app's version history. Needs a full-access key. Returns { id, version }.

Inputs: id (required).

send_batch_emailsSend batch emails (sends real email)A
Destructive

WARNING: this SENDS REAL EMAIL to real recipients through Cresca and cannot be undone (only a scheduled or still-queued email can be canceled). Confirm the recipients, sender and content with the user before calling it. Each recipient counts toward the plan's monthly email allowance.

POST /emails/batch. Sends 1 to 100 different emails in one request. Each item takes the same fields as send_email except attachments and scheduled_at, which batches do not support.

All or nothing: if any email is invalid, nothing is sent and the error names the failing email by zero-based index ("Email 3: ...").

Works with sending-access and full-access keys. idempotency_key is required and covers the whole batch: build it from the event ("weekly-digest/2026-W45") and reuse it on every retry. If the result says already_sent, the batch went out earlier: do not retry with a new key. Returns { data: [{ id }, ...] } in request order.

Inputs: emails (required), idempotency_key (required).

send_emailSend email (sends real email)A
Destructive

WARNING: this SENDS REAL EMAIL to real recipients through Cresca and cannot be undone (only a scheduled or still-queued email can be canceled). Confirm the recipients, sender and content with the user before calling it. Each recipient counts toward the plan's monthly email allowance.

POST /emails. Sends one transactional email to up to 50 recipients (to + cc + bcc), with html/text or a published template, optional attachments, tags, custom headers and scheduling up to 30 days ahead.

Works with sending-access and full-access API keys. The from address must be an active sender on a verified domain. Recipients on the suppression list are skipped and the call still succeeds.

idempotency_key is required: build it from the event ("order-confirmation/1042") and reuse it on every retry. If the result says already_sent, the email went out earlier: the task is done, do not retry with a new key. Returns { id }; check delivery with get_email.

Use it for transactional email (password resets, receipts, alerts), not newsletters or promotions: those belong in Cresca campaigns.

Inputs: to (required), idempotency_key (required), cc, bcc, +10 more.

update_scheduled_emailReschedule emailA
Idempotent

PATCH /emails/:id. Changes the send time of an email whose status is still "scheduled"; any other status returns 422 validation_error. The new time is ISO 8601, up to 30 days ahead. WARNING: a time in the past sends the email immediately. Needs a full-access key.

Inputs: id (required), scheduled_at (required).

update_templateUpdate template draftA
DestructiveIdempotent

PATCH /templates/:id. Changes a template's DRAFT, overwriting the fields you send (send only the ones to change; same formats as create_template). Live email keeps using the published version until publish_template is called. Send alias: null to remove the alias. Sending html replaces a visual-editor design with plain HTML. Needs a full-access key.

Inputs: id (required), from, html, name, +6 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool maps to a distinct resource+action pair, and the two send tools are clearly separated by semantics (one email to many recipients vs. many distinct emails in a batch), as are get_email vs. list_emails and update_scheduled_email vs. cancel_email. Template tools split cleanly along draft-vs-published lifecycle lines, so an agent can pick the right tool from the description alone.

    Naming Consistency5/5

    All names follow a single snake_case verb_noun convention (send_email, get_email, list_emails, create_template, publish_template, delete_template, add_contacts). The only variation is qualifying modifiers like batch and scheduled, which stay within the same pattern rather than introducing a new convention.

    Tool Count5/5

    Thirteen tools sit comfortably in the well-scoped range and each one covers a real operation: six email operations, six template lifecycle operations, and one contact import. There is no visible filler or redundant alias tool.

    Completeness3/5

    Email sending and the template lifecycle are covered end-to-end (send, batch, inspect, list, reschedule, cancel, draft, publish, delete), but the contacts surface is a single write-only add_contacts with no list/get/update/delete or suppression-list management, so an agent cannot verify or clean up contacts it imported. Suppression list handling is also only referenced implicitly, leaving notable dead ends outside the core send path.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to send transactional email, authenticate sending domains, track delivery, and diagnose deliverability issues programmatically.
      13
      74 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to send transactional emails and manage email infrastructure through the AgentiSend API, including domain verification, budgeted keys, and message logs.
      46
      99 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to send, receive, and track email and manage templates, domains, webhooks, and other email API operations from AI assistants.
      122 npm
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Enables AI assistants to send and track transactional email, manage templates, domains, webhooks, contact lists, agent mailboxes, and analytics through the EuroMail API, with mail processed in the EU.
      56
      47 npm
      MIT