MCPTool reference
Contacts
BlueSuite MCP tools for contacts
See connection and authentication and workflow rules before calling these tools.
Related REST API and behavior.
list_contacts
List contacts with optional pagination and search
Parameters
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
page | integer | No | Page number (default: 1) |
per_page | integer | No | Results per page (default: 25) minimum: 1. maximum: 100. |
search | string | No | Search by name, email, phone, or company |
sort_by | "id", "first_name", "last_name", "email", "phone", "company", "type", "created_at", "modified_at" | No | Field to sort by. There is no "name" field, use first_name or last_name. Unknown values fall back to the default sort. |
sort_direction | "asc", "desc" | No | Sort direction |
type | "none", "customer", "lead", "former_customer", "contractor", "partner", "vendor", "other" | No | Filter by contact type |
owner_id | string | No | Filter by owner user UUID. Use list_users to resolve names. Format: uuid. |
tag_ids | array of integer | No | Filter to records carrying ANY of these tag IDs (not all). Use list_tags with the matching taggable_type to resolve tag names to IDs first. |
Result
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
data | array of object | Yes | The matching records for this page. |
pagination | object | No | How many more pages of results exist. Absent when the API returned an unpaged result. |
pagination.page | integer | When parent supplied | Current page number, 1-based. |
pagination.per_page | integer | When parent supplied | Number of results per page. |
pagination.total_pages | integer | When parent supplied | Total number of pages available. |
create_contact
Create a new contact
Parameters
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
first_name | string | Yes | First name (required) |
last_name | string | Yes | Last name (required) |
email | string | No | Primary email address |
phone | string | No | Primary phone number |
secondary_email | string | No | Secondary email address |
secondary_phone | string | No | Secondary phone number |
company | string | No | Company name |
company_department | string | No | Department within company |
company_position | string | No | Position/title at company |
title | "mr", "mrs", "miss", "ms", "dr", "prof", "rev" | No | Honorific title |
type | "none", "customer", "lead", "former_customer", "contractor", "partner", "vendor", "other" | No | Contact type (default: none) |
owner_id | string | No | UUID of the contact owner. Use list_users to resolve names. Format: uuid. |
custom_fields | object | No | Custom field values |
Result
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
get_contact
Get a single contact by ID with expanded details (properties, activity)
Parameters
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
id | integer | Yes | Contact ID |
Result
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
update_contact
Update an existing contact
Parameters
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
id | integer | Yes | Contact ID |
first_name | string | No | First name |
last_name | string | No | Last name |
email | string | No | Primary email address |
phone | string | No | Primary phone number |
secondary_email | string | No | Secondary email address |
secondary_phone | string | No | Secondary phone number |
company | string | No | Company name |
company_department | string | No | Department within company |
company_position | string | No | Position/title at company |
title | "mr", "mrs", "miss", "ms", "dr", "prof", "rev" | No | Honorific title |
type | "none", "customer", "lead", "former_customer", "contractor", "partner", "vendor", "other" | No | Contact type |
owner_id | string | No | UUID of the contact owner. Use list_users to resolve names. Format: uuid. |
custom_fields | object | No | Custom field values |
Result
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
delete_contact
Delete a client. Their properties, follow-up tasks, notes and saved payment methods cascade away with them. Jobs, quotes and invoices remain but are left without a client. Confirm with the user first, especially when the client has live work, there is no undo.
Parameters
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
id | integer | Yes | Contact ID |
Result
| Field | Type / accepted values | Required | Details |
|---|---|---|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
The downloadable tool schemas include the full input and output contracts. Tables describe schema-level required fields; cross-field rules still apply.