Retainful MCP by usefulapi
List contacts and lists; create contacts, add them to lists and record events in Retainful.
使うべきか
品質と安全性
ツール定義とプロトコルへの準拠に関する自動分析に基づいています。
コンテキストコスト
これは、サーバーのツールがモデルのコンテキストに読み込まれるたびに消費されるおおよそのトークン数です。数が多いほど、ほかのタスクに使える注意が減ります。
インストール
ワンクリックインストール
これを `claude_desktop_config.json` ファイルに追加してください:
{
"mcpServers": {
"retainful": {
"url": "https://retainful.usefulapi.io/mcp"
}
}
}リモートエンドポイント
https://retainful.usefulapi.io/mcpstreamable-httpできること
ツール一覧
ツール（7）
🟢retainful_list_contacts(page, limit)
List contacts (profiles) in the Retainful organization, one page at a time, with consent status and source. Retainful API: GET /customer.
入力スキーマ
{
"type": "object",
"properties": {
"page": {
"description": "Page number (default 1).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"limit": {
"description": "Items per page (default 10, max 100).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢retainful_get_contact(contact_id)
Get one contact (profile) by its Retainful id (contactUUID), with its attributes. Retainful API: GET /customer/{id}.
入力スキーマ
{
"type": "object",
"properties": {
"contact_id": {
"type": "string",
"minLength": 1,
"description": "Retainful contact id, e.g. 01K8J5M02QYPEJE5YN3V944ZY9."
}
},
"required": [
"contact_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢retainful_list_lists(type, page, limit)
List the lists and segments in the organization with their ids. Use the id as list_id in retainful_add_contact_to_list. Retainful API: GET /contact-groups.
入力スキーマ
{
"type": "object",
"properties": {
"type": {
"description": "Filter by LIST, SEGMENT, or ALL (default ALL).",
"type": "string",
"enum": [
"LIST",
"SEGMENT",
"ALL"
]
},
"page": {
"description": "Page number (default 1).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"limit": {
"description": "Items per page (default 10, max 100).",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢retainful_get_list(list_id)
Get one list or segment by its id. Retainful API: GET /contact-groups/{id}.
入力スキーマ
{
"type": "object",
"properties": {
"list_id": {
"type": "string",
"minLength": 1,
"description": "Retainful list id from retainful_list_lists."
}
},
"required": [
"list_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴retainful_upsert_contact(email, phone, email_opt_in, phone_opt_in, first_name, ...)
WRITE: create a contact, or update it when the email or phone already exists. Does not add anyone to a list. email_opt_in is required: it sets marketing consent, so send SUBSCRIBED only with real consent. Needs email or phone. Retainful API: POST /customer/create.
入力スキーマ
{
"type": "object",
"properties": {
"email": {
"description": "Email address.",
"type": "string",
"maxLength": 255,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"phone": {
"description": "Phone number, 7-20 characters, needed for WhatsApp.",
"type": "string",
"minLength": 7,
"maxLength": 20
},
"email_opt_in": {
"type": "string",
"enum": [
"SUBSCRIBED",
"NON_SUBSCRIBED",
"UNSUBSCRIBED"
],
"description": "Email consent. Use SUBSCRIBED only when the person opted in. NON_SUBSCRIBED = no marketing email. UNSUBSCRIBED = opted out."
},
"phone_opt_in": {
"type": "string",
"enum": [
"SUBSCRIBED",
"NON_SUBSCRIBED",
"UNSUBSCRIBED"
],
"description": "Email consent. Use SUBSCRIBED only when the person opted in. NON_SUBSCRIBED = no marketing email. UNSUBSCRIBED = opted out."
},
"first_name": {
"type": "string",
"maxLength": 100
},
"last_name": {
"type": "string",
"maxLength": 100
},
"external_id": {
"description": "Your own id for this person, e.g. your database id.",
"type": "string",
"maxLength": 255
},
"source": {
"description": "Where the contact came from (default api).",
"type": "string",
"maxLength": 100
},
"custom_properties": {
"description": "Custom fields as string values. Maximum 30 keys.",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
}
},
"required": [
"email_opt_in"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴retainful_add_contact_to_list(list_id, email, email_opt_in, first_name, last_name, ...)
WRITE: create or update a contact by email and add them to a list in one call. A list can start an automation. email_opt_in is required: an existing contact is set to SUBSCRIBED when it is omitted here. Retainful API: POST /contact-groups/{listId}/contacts.
入力スキーマ
{
"type": "object",
"properties": {
"list_id": {
"type": "string",
"minLength": 1,
"description": "Retainful list id from retainful_list_lists."
},
"email": {
"type": "string",
"maxLength": 255,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
"description": "Email address of the contact (required here)."
},
"email_opt_in": {
"type": "string",
"enum": [
"SUBSCRIBED",
"NON_SUBSCRIBED",
"UNSUBSCRIBED"
],
"description": "Email consent. Use SUBSCRIBED only when the person opted in. NON_SUBSCRIBED = no marketing email. UNSUBSCRIBED = opted out."
},
"first_name": {
"type": "string",
"maxLength": 100
},
"last_name": {
"type": "string",
"maxLength": 100
},
"phone": {
"description": "Phone number, 7-20 characters, needed for WhatsApp.",
"type": "string",
"minLength": 7,
"maxLength": 20
},
"source": {
"description": "Where the contact came from (default api).",
"type": "string",
"maxLength": 100
}
},
"required": [
"list_id",
"email",
"email_opt_in"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴retainful_track_event(event_name, unique_identifier, contact_uuid, email, phone, ...)
WRITE: record one event on a contact's timeline. Automations triggered by the event can email the contact. Reuse the same unique_identifier only for a retry of the same real occurrence (a repeat does not trigger automations again); use a new one for each new occurrence. Event data must be flat: strings, numbers, or booleans. Retainful API: POST /events.
入力スキーマ
{
"type": "object",
"properties": {
"event_name": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Human-readable name, e.g. Appointment Booked. Keep the spelling stable."
},
"unique_identifier": {
"type": "string",
"minLength": 1,
"maxLength": 255,
"description": "Id of this occurrence, e.g. an order or booking id. Idempotency key."
},
"contact_uuid": {
"description": "Retainful contact id. Send this, or email or phone.",
"type": "string",
"minLength": 1
},
"email": {
"description": "Email address.",
"type": "string",
"maxLength": 255,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"phone": {
"description": "Phone number, 7-20 characters, needed for WhatsApp.",
"type": "string",
"minLength": 7,
"maxLength": 20
},
"event_data": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"string",
"number",
"boolean"
]
},
"description": "Flat key-value details of the event. At least one key. No nested objects."
}
},
"required": [
"event_name",
"unique_identifier",
"event_data"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}コミュニティ
エビデンス