Cresca MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Cresca MCP Server Send the password-reset template to ana@acme.com with NAME set to Ana."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_emailandsend_batch_emailssend 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 |
|
Check whether an email was delivered, bounced or is still queued |
|
Reschedule or cancel an email that has not gone out yet |
|
Draft, review, publish and delete email templates with |
|
Add people to a marketing contact list |
|
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_emailandsend_batch_emails. Every other tool returns401 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 APIThen 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 |
| yes | Your API key ( | |
| no |
| Base URL including |
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/mcpAdd --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 |
|
| Sends one email to up to 50 recipients, with HTML/text or a published template, attachments, tags, headers, scheduling | sending or full |
|
| Sends 1 to 100 different emails in one all-or-nothing request | sending or full |
|
| Retrieves one email and its latest status ( | full |
|
| Lists API emails, newest first, with cursor pagination | full |
|
| Changes the send time of a scheduled email | full |
|
| Cancels a scheduled or queued email | full |
|
| Creates a template draft | full |
|
| Lists templates, newest first | full |
|
| Retrieves a template by id or alias | full |
|
| Changes a template draft (live email keeps the published version) | full |
|
| Publishes the draft as the new live version | full |
|
| Permanently deletes a template | full |
|
| 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: truewith 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 |
Attachments per email | 20, up to 7 MB in total, base64 only |
Tags per email | 10, ASCII letters, numbers, |
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_emailsfor status instead)SMTP relay
Official SDKs (this server calls the REST API directly)
Attachments by URL (
path): send base64contentOpen 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
Authorizationheader toCRESCA_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; plainhttpis accepted only forlocalhostduring 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
.gitignoreexcludes.envfiles 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 |
| The client started the server without the key | Add |
| A Sending access key was used for a tool that reads or changes data | Use a Full access key for that tool |
| The | Verify the domain and add the sender in Sending Domains |
| The template is not published, or a required variable is missing | Publish the template, or pass every variable without a fallback |
| Too many requests per second for your plan | The server retries safe requests; otherwise wait and try again |
| The plan's monthly email allowance is used up | Upgrade the plan or wait for the next period |
The client cannot start the server |
| Use the full path to |
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 testnpm 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 toolsadd_contactsAdd contacts to a listAIdempotent
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 emailADestructive
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)ADestructiveIdempotent
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 emailARead-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 templateARead-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 emailsARead-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 templatesARead-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)ADestructive
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)ADestructive
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)ADestructive
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 emailAIdempotent
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 draftADestructiveIdempotent
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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
Send email, manage domains, templates, webhooks and broadcasts from your AI agent.
Transactional email for AI agents: templates, domain verify, and sends.
Email for AI agents: send from your verified domain, track delivery, list mail, validate addresses.
Email for AI agents — send, receive as a webhook, manage domains, templates, routing.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI agents to send transactional email, authenticate sending domains, track delivery, and diagnose deliverability issues programmatically.1374 npmMIT
- AlicenseAqualityBmaintenanceEnables AI agents to send transactional emails and manage email infrastructure through the AgentiSend API, including domain verification, budgeted keys, and message logs.4699 npmMIT

ZapSMTP MCP serverofficial
AlicenseNot gradedqualityBmaintenanceEnables MCP clients to send, receive, and track email and manage templates, domains, webhooks, and other email API operations from AI assistants.122 npmMIT- AlicenseCqualityCmaintenanceEnables 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.5647 npmMIT