@sure-shot/mcp-server-messaging

MCP server for the Sureshot Messaging API. Send rich RCS messages — text, cards, carousels — from any AI agent. Just provide a phone number and a message. We handle format selection, image enrichment, delivery, fallback to SMS, and reply forwarding.

Setup

1. Get an API key

Contact [email protected] to get your API key and onboard your RCS sender.

2. Configure in Claude Code

Add to your Claude Code settings (~/.claude/settings.json or project .claude/settings.json):

{
  "mcpServers": {
    "sureshot-messaging": {
      "command": "npx",
      "args": ["-y", "@sure-shot/mcp-server-messaging"],
      "env": {
        "SURESHOT_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Note: After adding the config, restart Claude Code (or your MCP client) for the new server to be available.

3. Start using it

Your agent now has four tools and a live event stream:

| Tool | What it does | |------|-------------| | send_message | Send text — we auto-detect the best rich format | | send_items | Send structured items as rich cards or carousels | | validate_email | Validate an email before sending — one decision-ready verdict | | validate_phone | Validate a phone — verdict, recommended channel, RCS capability, optional compliance |

Inbound replies are delivered in real time via MCP channel notifications (see Real-Time Events below).

Tools

send_message

Send a message to a phone number. We analyze the content and automatically render the best format — plain text, rich card with action buttons, or carousel.

Parameters:

• to (required) — Recipient phone number (any format)
• message (required) — Your message text
• quick_replies (optional) — Array of reply chips. Each item is either a plain string (postback auto-generated from the text) or { text, postback } when you need a stable machine-readable identifier echoed back on the inbound reply event. Use the object form when two chips share the same label, or when you want the inbound event to carry a stable ID you control.

Example: "Send a message to 9805551234 saying 'Check out today's deals at https://example.com — 30% off everything!'"

The API detects the URL and renders it as a tappable button. Phone numbers become call buttons. Addresses become directions. The response includes a suggestions array showing what action buttons and reply chips were generated.

send_items

Send structured items (products, events, sessions) as rich cards. 1 item = rich card, 2+ items = swipeable carousel.

Parameters:

• to (required) — Recipient phone number (any format)
• items (required) — Array of items, each with:
  • name (required) — Card title
  • url (required) — Tappable action button URL
  • price (optional) — Price or subtitle
  • description (optional) — Longer description
  • image (optional) — Image URL (auto-fetched from url if omitted)
• message (optional) — Intro text
• quick_replies (optional) — Reply chips. String (auto-postback) or { text, postback } object. See send_message for details.

Note on images: If images can't be sourced for all items in a carousel, the API automatically downgrades to a text message with inline tappable URLs. This is intentional — a mixed carousel (some cards with images, some without) looks broken. To guarantee carousel format, provide image URLs on every item.

validate_email

Validate an email address before you send to it. One call returns a decision-ready verdict from across multiple validators — your agent reads one field and acts.

Parameters:

• email (required) — Email address to validate (max 320 chars)

Returns: verdict (send / send_shared / send_risky / drop / drop_use_suggestion), reason_code, normalized, and a suggestion when there's a fixable typo (e.g. gmai.com → gmail.com).

validate_phone

Validate a phone number and learn how to reach it — clean a list before you send to it.

Parameters:

• phone (required) — E.164 (+19805551234) or a bare national number (US/+1 assumed for 10-digit input)
• include_compliance (optional) — Opt in to a compliance scrub (known-litigator / do-not-contact risk). Defaults to false; costs more, so use it for numbers you actually intend to contact.

Returns: verdict (send / send_caution / drop), recommended_channel (rcs / sms / voice / none), line_type with line_type_confidence, carrier, rcs_capable (+ rcs_features), and a compliance block (not_checked unless you opted in).

Example: "Send a product carousel to 9805551234 with Nike Air Max at $89.99 from https://example.com/nike and Adidas Ultraboost at $112 from https://example.com/adidas"

Real-Time Events

The server maintains a persistent WebSocket connection to the Sureshot gateway (wss://gateway.sureshot.io/v1/stream). When a customer replies to a message, the event is pushed to the agent as an MCP channel notification — no polling required.

The server includes instructions that tell the agent how to handle inbound messages:

• Treat each notification as a real person replying
• Respond using send_message or send_items
• Treat short replies (emoji, single words) as acknowledgments
• Honor "Stop" by not sending further messages

The connection automatically reconnects with exponential backoff (1s to 30s cap) if interrupted. Authentication failures (close code 4001) are treated as fatal and will not reconnect.

Event types your agent will see

Every channel notification includes a type attribute in meta. The rest of the meta attributes depend on the type:

| type | content | Key meta attributes | |---|---|---| | text | the user's typed message | from, timestamp, message_id | | reply | the chip label the user tapped | postback (machine-readable ID you assigned) | | button | the button label the user tapped | postback | | image / audio / video | (image received: filename.jpg) or similar | media_url, media_name | | location | (location shared: lat, lng) | location_lat, location_lng |

When the user reacts to a message (iOS tapback or custom emoji), the event arrives as type: text with additional reaction meta: reaction_type (liked, loved, laughed_at, disliked, emphasized, questioned, or reacted), reaction_emoji (custom-emoji reactions only), and reaction_original_text. Most agents should acknowledge briefly or ignore reactions rather than treat them as new instructions.

Note on media URLs: media_url points to a carrier-hosted endpoint that requires server-side authentication to fetch. Direct customer access is not yet supported — see the Sureshot API docs for the current media handling policy.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SURESHOT_API_KEY | Yes | — | Your Sureshot API key | | SURESHOT_API_URL | No | https://gateway.sureshot.io | API base URL (for local dev/staging) | | SURESHOT_ALLOWED_SENDERS | No | — | Optional allowlist of inbound senders. Comma-separated E.164 numbers (e.g. "+19198102290,+14155550100"). When set, only inbound events from listed numbers reach the agent; others are dropped (a one-line stderr log notes each drop, so typos surface quickly). Unset or "*" means emit all events. Formatting characters (spaces, dashes, parens) are stripped before comparison, so "+1 (919) 810-2290" and "+19198102290" are equivalent. |

Learn More

• API Documentation
• Sureshot