MCP tools for integrations, provider fields, and apps
Discover and connect integrations, inspect provider fields, test credentials, and retrieve connected Senja resources through MCP.
Use these MCP tools to connect your email platform or Senja, 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 are separate connections.
list-connectable-integrations
Discovers connection keys and credential slots before attempting a connection.
Arguments: optional project_id string.
Illustrative entry 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. 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. |
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, use fields: [{"key":"apiKey","value":"..."}] or api_key. Its 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.
create-integration
This registered compatibility operation connects API-key email platforms through the same save path. It does not connect Senja. 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.
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 and nullable verifiedAt.
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.