SendGrid Transactional

What the SendGrid Transactional MCP server does

The SendGrid Transactional MCP server exposes SendGrid’s transactional email workflow through MCP rather than attempting to cover the full SendGrid API. Its focus is the /v3/mail/send path, pre-send checks, post-send diagnostics, and the configuration that affects delivery.

Before sending, sendgrid_validate_send_request checks the message payload, active dynamic template version, sender authentication or verified sender, link branding, recipient suppressions, the applicable ASM group, the DMARC warning list, and scheduled-send timing. sendgrid_send_with_preflight sends only when the validation report has no blockers. Sandbox mode validates and accepts the payload without delivering mail.

After SendGrid accepts a message, sendgrid_get_message_activity follows the event chain using the x-message-id response value as xMessageId. Delivery triage includes sendgrid_check_suppression, sendgrid_triage_delivery_issue, sendgrid_delete_suppression, sendgrid_classify_sendgrid_error, and sendgrid_get_scopes. The server can also list paused or canceled scheduled batches.

How it works

The workflow separates checks before delivery from evidence gathered afterward. Activity searches use a message-ID prefix because the response header is not itself a msg_id. If Email Activity is unavailable or returns no data for the EU region, the server uses Email Logs with an exact to_email match. Email Logs do not accept msg_id, from_email, or LIKE filters.

Additional tools cover dynamic template management, including renaming and removing inactive versions. Event Webhooks can be created, updated, or tested on the SendGrid side. An optional local receiver stores incoming events in memory so they can be read with sendgrid_get_received_webhook_events and inspected with sendgrid_get_webhook_receiver_status.

Setup and configuration

Running the SendGrid Transactional MCP server requires Bun 1.4.3 or newer, a SendGrid API key with the scopes needed by the selected tools, and a verified address in SENDGRID_FROM_EMAIL. The documented installation command is bunx --no-env-file x @neschadin/sendgrid-mcp.

Set SENDGRID_API_KEY and SENDGRID_FROM_EMAIL for the required configuration. Optional settings select the global or EU API region, override the API host, set a default subuser or account context, configure logging, and enable read-only mode. READ_ONLY=true blocks sending and mutating operations before an API request.

The default transport is stdio. Setting MCP_TRANSPORT=http exposes Streamable HTTP at /mcp; token authentication, host and origin allowlists, and optional TLS settings control remote use. Cursor and Claude Desktop examples are provided, and VS Code is listed as a supported MCP client. A local Event Webhook receiver is enabled only when its port variable is configured.

Tools and capabilities

• Validate a send request and send only after a clean preflight.
• Inspect Email Activity or fall back to Email Logs where documented.
• Check, investigate, and remove suppression records.
• Explain SendGrid authorization failures and inspect available scopes.
• Manage templates and Event Webhooks.
• Configure domains, link branding, enforced TLS, mail and tracking settings, alerts, and inbound parse.

Mutating tools, including sends, require confirmToken set to CONFIRM, except that send tools do not request that token. Use preflight or read-only mode when an agent must not send mail.

Limitations and notes

The SendGrid Transactional MCP server does not cover contacts, lists, campaigns, or the broader marketing API. One process is intended to use one API key; the README advises against sharing a hosted instance across tenants.

The local webhook receiver keeps its buffer in memory and discards events when the process exits. Its default capacity is 5,000 events. A scheduled message that only received send_at will not appear in the paused or canceled batch list until it is paused or canceled. Tool calls containing more than 10,000 combined array elements and object members are rejected, and sensitive oauth_client_secret and api_key values are masked in results.