Wraps Logo
DocsHome
MCP Reference

MCP Server

@wraps.dev/mcp gives AI agents access to your AWS SES sending history, delivery events, domain status, and suppression list — and, optionally, the ability to send email. It runs locally over stdio; your AWS credentials never leave your machine.

Hosted server: docs and pricing

There is a second, public server at https://wraps.dev/mcp over the Streamable HTTP transport. It answers questions about Wraps — it never touches your AWS account, so it needs no credentials, no API key, and no account. Four read-only tools: search_docs, get_doc, list_docs, and estimate_cost.

JSON.mcp.json
{  "mcpServers": {    "wraps-docs": {      "type": "http",      "url": "https://wraps.dev/mcp"    }  }}

Or call it directly — it is plain JSON-RPC over HTTPS:

terminal
curl -s https://wraps.dev/mcp \  -H 'content-type: application/json' \  -H 'accept: application/json' \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A manifest covering both servers is published at /.well-known/mcp.json. Everything below this section is about the local server.

Prerequisites

Before you begin, make sure you have:

  • A Wraps email stack deployed (wraps email init)
  • AWS credentials configured in your environment — the same profile the Wraps CLI uses
  • A Wraps API key (WRAPS_API_KEY) or a wraps auth login session, for the API-backed tools

Tools

The server exposes the AWS tools and, with a Wraps API credential, the API-backed tools. Tools marked write change data and stay disabled until WRAPS_WRITE_ENABLED=true. Destructive tools also need confirm: true.

ToolDescriptionAccess
list_recent_sendsList recent sends from your email historyread
get_email_event_logFull delivery event log for a message (Send, Delivery, Bounce, Complaint, Open, Click)read
verify_domain_statusVerification and DKIM status of a sending domainread
list_suppressionsAddresses on your SES suppression list, filterable by BOUNCE or COMPLAINTread
estimate_costMonthly Wraps + AWS cost for a send volume, including which SES pricing plan the account is on — needs no AWS credentialsread
get_setup_statusCheck whether the account is in the SES sandbox, and get the next step toward a first sendread
send_emailSend a transactional email via your SES account (requires WRAPS_WRITE_ENABLED=true)write
check_send_statusPoll the outcome of a pending_approval send by approvalId (enforced mode only)read
list_contactsList contacts in your Wraps organization, optionally filtered by email status, SMS status, preferred channel, or a search string on email or phone.read
get_contactGet one contact in full, including its topic subscriptions.read
create_contactCreate one new contact.write
update_contactChange one existing contact.write
set_contact_topicsREPLACE the full topic subscription list of one contact.write
delete_contactPermanently delete ONE contact by UUID, email, or externalId. Needs confirm: true.write
validate_contact_emailsCheck up to 100 email addresses with SES Email Address Insights and return a deliverability verdict (HIGH, MEDIUM, LOW, or UNKNOWN) for each.read
export_contactsExport the contacts that match optional filters, newest first, up to 1,000 rows per call. truncated is true when more contacts matched; there is no paging, so narrow the filters and call again.read
import_contactsImport up to 10,000 contacts in one call and get back created, updated, skipped and invalid counts, with the reason for each rejected row. Changing existing contacts (duplicateStrategy update) needs confirm: true.write
list_segmentsList the audience segments saved in this Wraps organization, with each segment's live member count.read
get_segmentGet one audience segment by id, including its full filter condition and live member count.read
preview_segmentPreview the audience an unsaved filter condition would reach, without saving a segment.read
create_segmentSave a new audience segment from a filter condition.write
update_segmentChange an existing audience segment: rename it, edit its description, replace its condition, or toggle trackMembership.write
delete_segmentPermanently delete an audience segment. Needs confirm: true.write
list_topicsList the organization's subscription topics with live audience counts: subscriberCount (opted in), sendableCount (a broadcast would reach now) and pendingCount (waiting on double opt-in).read
get_topicGet one subscription topic by id, with its audience counts (subscriberCount, sendableCount, pendingCount) and its creator.read
list_topic_subscribersList the contacts subscribed to one topic, filtered by status (subscribed, pending for double opt-in not yet confirmed, or unsubscribed).read
create_topicCreate a subscription topic that contacts can subscribe to and broadcasts can target.write
update_topicChange a subscription topic's name, slug, description, public flag or double opt-in setting.write
delete_topicPermanently delete a subscription topic and every subscription to it. Needs confirm: true.write
list_templatesList the Wraps email and SMS templates in your organization.read
get_templateGet one Wraps template by id: its metadata, status, variables, and by default its React Email source, compiled HTML, and compiled text.read
create_templateCreate a new Wraps email or SMS template as a DRAFT.write
update_templateChange an existing Wraps template.write
duplicate_templateCopy an existing Wraps template to start a variant.write
publish_templatePublish a Wraps template to SES, so sends and workflows that use it get this content. Needs confirm: true.write
delete_templatePermanently delete up to 100 templates, with their versions, and their published SES copies where no other template uses the same SES name. Refused with 409 (nothing deleted) while a draft, scheduled, queued or processing broadcast, or an enabled workflow, uses one. Needs confirm: true.write
list_broadcastsList broadcasts (email or SMS batch sends) for your organization, with their status and delivery counts.read
get_broadcastGet the status and delivery counts of ONE broadcast by id.read
list_broadcast_recipientsList the per-recipient outcome of one broadcast: who was sent to, and whether each send was delivered, bounced, suppressed or failed, with the error reason.read
get_broadcast_clicksGet the link-click breakdown for ONE broadcast: which URLs were clicked and how often, plus the unsubscribe click count.read
create_broadcastCreate a NEW broadcast as a draft.write
update_broadcastEdit a SCHEDULED broadcast before it sends: its content, sender, audience, template, AWS account or send time.write
duplicate_broadcastCopy an existing broadcast into a NEW draft, whatever the status of the original.write
send_broadcastSend a DRAFT broadcast to its audience, now or at scheduledFor. Needs confirm: true.write
resume_broadcastResume an email broadcast that stopped part-way, from the last chunk it finished, so recipients who were not yet sent to get the message. Needs confirm: true.write
cancel_broadcastCancel a broadcast that is scheduled, queued or processing, so the messages that have not gone out yet are not sent. Needs confirm: true.write
list_eventsList custom events tracked for this Wraps organization, newest first, optionally filtered by event name, contact, text search, or date range.read
get_eventGet one custom event by id: its name, properties, time, and the contact it belongs to.read
get_event_analyticsGet custom-event totals for this organization over the last 7 or 30 days: events in the period, active contacts, average events per contact, a zero-filled daily series, and the top event names.read
list_event_namesList every distinct custom event name recorded for this Wraps organization, sorted.read
track_eventRecord a custom event for one contact. Needs confirm: true.write
add_suppressionAdd up to 100 addresses to the SES account-level suppression list of one AWS account, so Wraps stops sending to them. Undo one address at a time with remove_suppression. Needs confirm: true.write
remove_suppressionRemove one address from the SES account-level suppression list of one AWS account, so Wraps sends to it again. Needs confirm: true.write
list_workflowsList the email and SMS automation workflows in your Wraps organization, newest first, with status and execution counts.read
get_workflowGet one workflow by id, including its trigger config, steps and transitions, so you can see what it does before triggering it or changing its schedule.read
list_workflow_executionsList the executions of one workflow (one run per contact), newest first, each with its contact and status.read
get_workflow_executionGet one workflow execution by id, with its step trace (every step it reached and that step status), its contact, the workflow name and per-step engagement.read
enable_workflow_scheduleTurn on the recurring schedule of a schedule-triggered workflow by creating its next one-time run from a cron expression and timezone.write
disable_workflow_scheduleTurn off the recurring schedule of a schedule-triggered workflow by deleting its pending scheduled run.write
trigger_workflowStart one run of an API-triggered workflow for one contact, so the workflow steps begin for that contact now. Needs confirm: true.write
retry_workflow_executionRetry a failed workflow execution from the step where it failed. Needs confirm: true.write
cancel_workflow_executionCancel a workflow execution that is still running (pending, active, paused or waiting), so no further steps run for that contact and its scheduled steps are removed. Needs confirm: true.write
list_agentsList the leashed agents in your organization: each one's sending address, send policy (hourly and daily caps and recipient allowlists), and whether it is ACTIVE or KILLED.read
create_agentCreate a leashed agent: a named sender with its own address and send policy. Recorded in Wraps only; its AWS resources are deployed with the CLI. Needs an owner or admin. Not registered in enforced mode.write
kill_agentKill one leashed agent so it can no longer send. Irreversible: no route returns a killed agent to ACTIVE. Needs an owner or admin and confirm: true. Not registered in enforced mode.write
set_agent_policyReplace one leashed agent's send policy in full: hourly and daily caps and both recipient allowlists. Overwrites the previous policy. Needs an owner or admin and confirm: true. Not registered in enforced mode.write
list_agent_approvalsList the approval queue for agents: the sends that an agent asked to make and that were held for a human decision.read
approve_agent_approvalApprove one send that an agent asked to make and that was held for a human decision, so Wraps sends it now. Needs confirm: true.write
reject_agent_approvalReject one send that an agent asked to make and that was held for a human decision, so it is never delivered. Needs confirm: true.write
get_email_metricsGet aggregate email sending metrics for this organization over a time window: sent, delivered, bounced (split into permanent, transient and undetermined), complained, suppressed, opened, clicked, failed, and an estimated costUsd.read
list_inbound_emailsList one page of parsed inbound emails that the customer's SES inbound bucket received, across the organization's connected AWS accounts. Each entry carries envelope recipients (when recorded).read
get_inbound_emailGet one parsed inbound email from the customer's SES inbound bucket by emailId, with its from/to/cc, subject, date, headers, text body, HTML body, attachment metadata and envelope recipients (when recorded).read
get_account_healthGet the SES sending health of the AWS accounts connected to your organization: status, when it was last checked, quota, reputation and the reasons for the status. Reads the verdict the hourly sweep last saved, with no AWS calls.read
email_checkCheck a domain's SPF, DKIM, DMARC, MX, blacklist and related setup, and return a grade with the issues that cost points. Read-only, sends no mail. The request is public and rate limited to 10 per minute per IP.read
list_brand_kitsList the organization's brand kits: name, logo, colors, fonts, button style, company details and social links, with isDefault marking the one default kit.read
get_brand_kitGet one brand kit by id: logo, colors, fonts, button style, company details, social links, and isDefault.read
create_brand_kitCreate a brand kit: a name, logo, colors, fonts, button style, company details and social links that email templates can use.write
update_brand_kitChange one or more fields of a brand kit: name, logo, colors, fonts, button style, company details, social links.write
set_default_brand_kitMake one brand kit the default for the organization.write
delete_brand_kitDelete a brand kit permanently. Needs confirm: true.write

Setup

Claude Code

Add to .mcp.json in your project root. Claude Code passes your shell environment through, so whichever AWS credentials you already use are picked up. Set AWS_REGION here regardless: the server reads the region from its own environment — either that or AWS_DEFAULT_REGION — and never from your AWS config file, so it exits on startup without one.

JSON.mcp.json
{  "mcpServers": {    "wraps": {      "command": "npx",      "args": ["-y", "@wraps.dev/mcp"],      "env": {        "AWS_REGION": "us-east-1"      }    }  }}

Claude Desktop, Cursor, Windsurf

GUI clients inherit nothing from your shell, so any credential settings belong in the same env block alongside the region. For Claude Desktop the file is ~/Library/Application Support/Claude/claude_desktop_config.json; for Cursor it's .cursor/mcp.json.

JSONclaude_desktop_config.json
{  "mcpServers": {    "wraps": {      "command": "npx",      "args": ["-y", "@wraps.dev/mcp"],      "env": {        "AWS_REGION": "us-east-1",        "AWS_PROFILE": "your-aws-profile"      }    }  }}

API-backed tools

The API-backed tools call the Wraps API for your organization. They register at startup only when a credential is present. Write tools need WRAPS_WRITE_ENABLED=true. Destructive tools also need confirm: true in the call, so set it only after the user has confirmed the change.

The server uses WRAPS_API_KEY when it is set. Otherwise it reuses the unexpired session that wraps auth login stored. An expired or revoked credential does not stop startup; the call returns a tool error that names the fix.

JSON.mcp.json
{  "mcpServers": {    "wraps": {      "command": "npx",      "args": ["-y", "@wraps.dev/mcp"],      "env": {        "AWS_REGION": "us-east-1",        "WRAPS_API_KEY": "wraps_..."      }    }  }}

When WRAPS_AGENT_ID is set (enforced mode), approve_agent_approval, reject_agent_approval, create_agent, kill_agent and set_agent_policy are not registered, so an enforced agent cannot approve or reject its own sends, or create agents, kill them or change their policies. list_agents stays registered.

Configuration

All configuration is via environment variables.

VariableRequiredDefaultDescription
AWS_REGIONYes—AWS region where your Wraps stack is deployed
WRAPS_HISTORY_TABLE_NAMENowraps-email-historyDynamoDB table name for email history
WRAPS_ACCOUNT_IDNoauto-detected via STSYour AWS account ID (skips the STS call if set)
WRAPS_WRITE_ENABLEDNofalseSet to true to enable send_email and every write or destructive API-backed tool
WRAPS_FROM_EMAILNo—Default from address for send_email
WRAPS_CONFIGURATION_SETNo—SES configuration set applied to sends (enables open/click tracking)
WRAPS_API_KEYNo—Wraps API key (wraps_...) for the API-backed tools. Without it, the session from wraps auth login is used
WRAPS_API_URLNohttps://api.wraps.devWraps API base URL. Set it for a self-hosted control plane
WRAPS_ORG_IDNo—Organization to act in when the session belongs to several. Sent as x-organization-id

Write mode

send_email is disabled by default. Set WRAPS_WRITE_ENABLED=true to enable it, along with every other write tool. The from address must belong to a domain verified in your SES account.

JSON.mcp.json
{  "mcpServers": {    "wraps": {      "command": "npx",      "args": ["-y", "@wraps.dev/mcp"],      "env": {        "AWS_REGION": "us-east-1",        "WRAPS_WRITE_ENABLED": "true",        "WRAPS_FROM_EMAIL": "you@yourdomain.com",        "WRAPS_ALLOWED_RECIPIENT_DOMAINS": "yourcompany.com"      }    }  }}

No allowlist means no limits

Running with WRAPS_WRITE_ENABLED=true and no allowlist gives the agent unrestricted send capability to any address your SES account can reach. Set the guardrails below.

Send guardrails

These variables apply to send_email only. When write mode is enabled, use them to restrict the agent's sending scope. A recipient is allowed if it matches either the address list or the domain list.

VariableDefaultDescription
WRAPS_ALLOWED_RECIPIENTS— (no restriction)Comma-separated exact addresses the agent may send to. If set, any address not in this list (or the domains list) is rejected.
WRAPS_ALLOWED_RECIPIENT_DOMAINS— (no restriction)Comma-separated domains the agent may send to. Matching is exact: example.com allows user@example.com but not subdomains — list each subdomain explicitly.
WRAPS_MAX_RECIPIENTS50Maximum number of recipients per send_email call.
WRAPS_ALLOW_FROM_OVERRIDEfalseSet to true to let the agent supply a from address that differs from WRAPS_FROM_EMAIL. When false, a mismatched from is rejected.

Enforced mode

For agents provisioned via wraps email agent create, the MCP server runs in enforced mode. The agent's AWS credential can only invoke an enforcer Lambda in your account — never SES directly. Kill-switch, recipient allowlist, and hourly/daily caps are decided by that Lambda, so the local guardrails above don't apply.

Enforced mode activates when both WRAPS_AGENT_ID and WRAPS_AGENT_ENFORCER_ARN are set. send_email then returns a structured disposition instead of an error for policy outcomes:

  • sent — delivered, with a messageId
  • pending_approval — an operator must approve; poll check_send_status with the returned approvalId
  • blocked — refused by policy (kill-switch, allowlist, or caps), with a reason

One recipient per send

Enforced mode accepts a single recipient per call. Pass one address (or a one-element array); larger arrays are rejected — send one email per recipient.

Next Steps

Agent Email Quickstart

Deploy SES and wire a typed send-email tool into your agent framework.

View Quickstart
Email SDK Reference

Every method, option, and response shape in @wraps.dev/email.

View SDK Docs

Need Help?

Open an issue or join the GitHub discussions — we read every one.

Get Help