MCP tools for integrations, provider fields, and apps
Discover and connect integrations, including Senja and Stripe, inspect provider fields, test credentials, and retrieve connected Senja resources through MCP.
Use these MCP tools to connect your email platform, Senja, or Stripe, check a connection, and find provider fields. Connection changes and provider field creation take effect immediately in your account or the external service. They aren't unpublished website edits. Configuration undo cannot reverse them.
MCP integration access and credentials
Every operation accepts an optional string project_id and follows the shared MCP authorization and project-selection rules. Invalid IDs, missing project selection, unavailable MCP access, and cross-project access return errors.
Examples are illustrative and were not executed. Requests show tools/call parameters; responses show decoded content. Response excerpts are labeled. Credentials in examples are deliberately fake. Never include real keys in a report or saved prompt.
OAuth email-platform connections must be established in the RightMessage dashboard using the returned setup_url. These tools cannot complete an OAuth authorization flow. A project can have one active email/CRM integration; credentialed apps such as Senja and Stripe are separate connections.
list-connectable-integrations
Discovers connection keys and credential slots before attempting a connection.
Arguments: optional project_id string.
Illustrative app entries from integrations:
The envelope is {integrations: [...], total, connected}. Entries are sorted connected-first, then by label. Each has key, label, kind (email or app), auth_type, connectable, connected, needs_reconnect, and fields. Field entries contain key, label, help, and required. Email entries also have integration_version; app entries have unlocked_tools. Apps with a setup guide, such as Stripe, add setup_url and setup_steps. When Stripe stopped accepting the stored key, the entry has needs_reconnect: true and a reconnect_reason. OAuth entries have no credential fields, connectable: false, and dashboard setup_url/setup_note.
Email field slots are api_key, api_secret, and api_secret_two; their labels describe provider-specific meaning. The catalog marks only the first email slot required, but provider validation can still require later slots. This local catalog read neither validates saved credentials upstream nor returns their values.
connect-integration
Validates and saves an API-key email connection or a credentialed app connection.
| Argument | Type | Required | Meaning |
|---|---|---|---|
project_id | string | No | Project to connect. |
integration | string | One key required | Key from the connection catalog. |
provider | string | Alternative | Alias for integration; if both are present they must match after trimming/lowercasing. |
api_key | string | Provider-dependent | Primary credential, sometimes an account API URL. Also accepted for Senja and Stripe. |
api_secret | string | Provider-dependent | Second email-platform credential. |
api_secret_two | string | Provider-dependent | Third credential, such as a site or publication ID. |
fields | array of objects | No | Each entry requires string key and string value. |
For email platforms, fields recognizes the three credential-slot names above; nonempty top-level slots take precedence. For Senja and Stripe, use fields: [{"key":"apiKey","value":"..."}] or api_key. The key must be 1–4,096 printable ASCII characters without whitespace. Duplicate app field keys use the last value.
App connections are checked upstream before saving. Reconnecting replaces existing app credentials and returns created: false, replaced: true. Senja verification reads its resource catalog.
Email success returns created, provider, integration_version, and, for newer connections, health. This tool adds integration, kind: "email", project_id, unlocked_tools: [], tools_changed: false, and hint. Healthy newer connections update the successful-connection timestamp and refresh tags. Userlist can be saved with pending health when an authorized test write is still needed. Connection creation is not proof that this later verification succeeded.
Every successful connection sends notifications/tools/list_changed. Restart the chat if your client does not refresh. Unknown keys, conflicting aliases, missing/malformed credentials, rejected keys, provider outages, existing email connections, and a different active email provider return errors. Email reconnect requires deleting the old connection first; app reconnect does not. OAuth connections return dashboard-only guidance.
Connecting Stripe
Stripe needs a restricted key (rk_live_…, or rk_test_… for test data) with Read access to Charges, Customers, and Subscriptions. Connect Stripe and see which segments buy walks through creating one.
The key is checked before anything is saved:
- A secret key (
sk_) is refused: "This is a secret key with full access to your Stripe account. Create a restricted key instead; RightMessage only needs to read charges, customers and subscriptions." - A publishable key (
pk_) is refused: "This is a publishable key. RightMessage needs a restricted key (starts with rk_live_)." - Anything else that doesn't start with
rk_live_orrk_test_is refused. - RightMessage tries reading Charges, Customers, and Subscriptions, and names every permission the key is missing in one error. A deleted or rolled key is rejected by Stripe.
A saved Stripe connection starts importing payments: the last 90 days first, then older history and new payments as they arrive. connection.sync reports state (importing, ready, delayed after 3 hours without a successful sync, or reconnect when Stripe stopped accepting the key), livemode (false for an rk_test_ key), lastSyncedAt, and message. Senja connections have sync: null.
Reconnecting Stripe with a new key replaces the connection. Payments imported with the old key are deleted and history is re-imported from scratch, starting with the last 90 days. get-segment-revenue reports revenue once the last 90 days are in.
create-integration
This registered compatibility operation connects API-key email platforms through the same save path. It does not connect Senja or Stripe. Prefer connect-integration for new clients.
Arguments: optional project_id string; required provider and api_key strings; optional api_secret and api_secret_two strings. Credential meanings come from list-connectable-integrations.
Illustrative response excerpt:
The response does not add the newer operation's app fields, tool-refresh hint, or notification. Older connection paths return only created, provider, and integration_version. External validation, immediate storage, email-provider conflicts, OAuth restrictions, pending test-write handling, and failure modes are the same as connect-integration.
list-integrations
Lists available email platforms and their capabilities, not credentialed apps.
Arguments: optional project_id string.
Illustrative entry from the response's integrations array:
The envelope contains integrations, total, and connected. Every entry has the first eight fields shown, with supported_features drawn from tags, custom_fields, lists, events, automations, and native_fields. Connected entries add timestamps. OAuth entries add setup_url and setup_note.
Older connections can appear as needs_reconnect: true and is_connected: false. This local metadata read does not prove live provider health or enumerate contacts.
get-integration
Returns detailed local metadata for one email provider.
Arguments: optional project_id string; required provider string, trimmed and lowercased.
Illustrative response excerpt:
Provider metadata adds label, auth_type, esp_feature_support, can_personalize_emails, and, where provided, setup_instructions. Feature-support metadata is provider-defined rather than one universal nested schema. Older connections expose last_ping_at and last_ping_succeeded instead of the newer health fields. Unconnected OAuth providers include setup guidance.
No credentials are returned. Missing provider input or an unknown provider returns an error. This operation reads saved status; it does not make a live health check. Its older-connection is_connected value is not the reconnect policy reported by list-integrations.
get-integration-data
Reads the connected provider's field, tag, and list catalogs.
| Argument | Type | Required | Default |
|---|---|---|---|
project_id | string | No | Active or eligible project. |
provider | string | Yes | Connected email provider key. |
data_types | array | No | All available types when omitted or empty. |
Recognized type strings are custom_fields, tags, lists, and native_fields. The declared item schema allows strings or numbers, but numbers and unknown strings do not identify a catalog.
The response contains provider, integration_version, and available requested catalog keys. Catalog items retain provider-specific field shapes. Newer list objects normalize to {id, name, is_static}; already-array list items pass through. Each failed catalog can produce <type>_error instead of its data, so an otherwise successful response can be partial. Unsupported newer-provider methods are omitted, not fabricated as supported empty catalogs.
The newest connection is used, preferring the newer integration system. Missing connections and provider-initialization failures are MCP errors. Reads can call the external provider but do not change a field or subscriber.
create-custom-field
Creates a field in the external email platform. Check existing fields and provider support first.
Arguments: optional project_id string; required provider string and nonempty label string; optional type string, default text. Provider and type are trimmed/lowercased; label is trimmed. Types such as number and date depend on the provider.
field.id is the provider ID. label falls back to the requested label; slug uses the provider's templating token, key, or ID. This does not itself map a dimension or publish configuration. Unstructured providers may accept arbitrary field keys without pre-creation.
Missing connections, changed credentials during dispatch, unsupported field creation, and provider errors return errors. A response saying the field was created but no valid response/ID was returned means the external write may already have happened. Inspect the provider dashboard before retrying to avoid duplicates.
test-integration
Checks saved email-provider credentials and reachability.
Arguments: optional project_id string; required provider string.
The response has provider, integration_version, healthy, message, and tested_at; newer-provider responses normally add provider-defined details. A thrown newer-provider exception returns healthy: false with Health check failed: ..., not necessarily an MCP error. Missing connections are MCP errors.
This makes an external health request and can update saved health timestamps. It is not a no-side-effect local read, a synchronization test, or proof that every provider write is authorized. No website publication is needed.
delete-integration
Disconnects an email provider by removing all its saved connections for this project, including older duplicates.
Arguments: optional project_id string; required provider string.
This immediately removes credentials and refreshes tags. It is not a draft edit and cannot be reversed with configuration undo. Existing collected visitor data and segment assignments remain. The operation does not disconnect apps or revoke credentials in the provider's own account. A missing connection returns No integration found for provider: ....
get-dimension-sync-data
Reads published dimension-to-provider mappings. Despite the tool description mentioning Liquid examples, the actual response is mapping data, not generated templates.
Arguments: optional project_id string.
Note the capital Name. Each entry includes the fields shown. Only dimensions with both a sync destination and custom field are included, and only segments with non-null sync values appear. Question text has markup removed and phrase fallbacks rendered. No published configuration or no mapped dimensions returns []. This does not fetch contacts, write provider fields, or include unpublished mappings.
list-apps
Lists registered non-email apps, their activation metadata, and local connection status. This tool is exposed only when Senja is connected to the selected project; connecting only Stripe doesn't add it.
Arguments: optional project_id string.
Illustrative Senja entry from the response's apps array:
The envelope is {apps: [...]}. Each entry has key, listing (name, logo, description, category), activation, and connection. Credential activation contains kind: "credentials" and a scheme; other apps use their own activation metadata and have connection: null. Credential connection status contains connected, nullable verifiedAt, and sync (the Stripe import status described above, or null).
This does not call providers or expose key values. Use the always-available connection catalog to discover and connect Senja before this conditional tool appears.
get-app-resources
Fetches a connected app's public editor catalog using stored credentials. Like list-apps, it is exposed only for a Senja-connected project.
Arguments: optional project_id string and required app string. No credential arguments are accepted.
Senja returns widgets with string id, name, design and boolean floating, plus wallsOfLove with string slug, permalink, and name. Popup, toast, and recent-sales designs are marked floating. The response contains catalog metadata, not credentials or a newly installed embed.
Missing app keys, unsupported apps, and disconnected apps return errors. Rejected credentials request reconnection; provider timeouts and failures return retry guidance. Creating an embed is a separate configuration action. Floating widgets need a page target, while nonfloating embeds can target an element; there is no RightMessage-widget target. Publishing that configuration is separate from reading this catalog.