MCP tools and resources

The MCP server offers 11 tools and 2 resources. Each tool runs the public API with your credential, so its permissions, limits and sandbox rules are the API’s. These are the input schemas tools/list returns.

Sending rules

Every sending tool’s description repeats these rules, so agents don’t trip the governor: Never message contacts who opted out. When the workspace requires consent, only contacts who opted in can be messaged. Sends outside 9 AM–8 PM in the contact’s local time are deferred. Until a contact replies, messages must be under 300 characters, contain no links, media, phone numbers or emails, and at most 3 can be sent.

Resources

• bubbl3://conversations/{id}
• bubbl3://contacts/{id}

Reading a resource runs get_conversation or get_contact, so it is checked and logged the same way.

send_message

Send a message. Never message contacts who opted out. When the workspace requires consent, only contacts who opted in can be messaged. Sends outside 9 AM–8 PM in the contact’s local time are deferred. Until a contact replies, messages must be under 300 characters, contain no links, media, phone numbers or emails, and at most 3 can be sent.

Field	Type	Required	Description
to	string	No	Recipient phone number in E.164. Provide to or contact_id.
contact_id	string	No	Contact id (ctc_...).
body	string	Yes	Up to 2000 characters.
pool_id	string	No	Pool id (pool_...).
fallback	boolean	No	Allow SMS if the contact is not on iMessage.
idempotency_key	string	No	Optional. Sent as the Idempotency-Key header: retrying with the same key returns the first message instead of sending again. Keys starting with outreach:, workflow: or agent: are refused. Up to 255 characters.

list_conversations

List recent conversations.

Field	Type	Required	Description
status	enum	No	One of: open, snoozed, closed.
assignee	enum	No	One of: me, unassigned, any. Default "any".
limit	integer	No	From 1 to 100. Default 20.

get_conversation

Get the messages in a conversation.

Field	Type	Required	Description
conversation_id	string	Yes	Conversation id (cnv_...).
limit	integer	No	Most recent messages to return. From 1 to 200. Default 50.

reply_to_conversation

Reply in an existing conversation. Never message contacts who opted out. When the workspace requires consent, only contacts who opted in can be messaged. Sends outside 9 AM–8 PM in the contact’s local time are deferred. Until a contact replies, messages must be under 300 characters, contain no links, media, phone numbers or emails, and at most 3 can be sent.

Field	Type	Required	Description
conversation_id	string	Yes	Conversation id (cnv_...).
body	string	Yes	Up to 2000 characters.
idempotency_key	string	No	Optional. Sent as the Idempotency-Key header: retrying with the same key returns the first message instead of sending again. Keys starting with outreach:, workflow: or agent: are refused. Up to 255 characters.

search_contacts

Search contacts.

Field	Type	Required	Description
query	string	Yes	Name, phone, email or company. Up to 100 characters.
limit	integer	No	From 1 to 100. Default 20.

get_contact

Get one contact by id or phone.

Field	Type	Required	Description
contact_id	string	No	Contact id (ctc_...).
phone	string	No	Phone number in E.164 format.

upsert_contact

Create a contact or update the one with this phone number. Does not change consent.

Field	Type	Required	Description
phone	string	Yes	Phone number in E.164 format.
email	string (email)	No	Up to 254 characters.
first_name	string	No	Up to 100 characters.
last_name	string	No	Up to 100 characters.
company	string	No	Up to 200 characters.
fields	object	No

check_imessage

Check whether a number can receive iMessage (cached for 30 days).

Field	Type	Required	Description
phone	string	Yes	Phone number in E.164 format.

list_lines

List lines with health and the new-contact capacity left today.

Field	Type	Required	Description
pool_id	string	No	Pool id (pool_...).

get_message_status

Get a message’s status and delivery timeline.

Field	Type	Required	Description
message_id	string	Yes	Message id (msg_...).

handoff_to_human

Hand the conversation to a person and notify the assigned team.

Field	Type	Required	Description
conversation_id	string	Yes	Conversation id (cnv_...).
reason	string	Yes	Up to 500 characters.
team_id	string (uuid)	No