Clients (customer CRM) module — JetSetGo MCP reference

The clients module is JetSetGo's customer relationship manager and the platform's largest MCP module. A client is a person or organisation the business sells to — the counterpart on every booking, invoice, and payment. The module owns the client record plus its whole relationship graph: addresses, secondary contacts, the communication log, unified document storage, saved fare-item templates, the self-service portal account, and real outbound messaging.

What the operator uses it for

Finding customers (full-text search over names/emails/phones, recents, location filters), keeping their details current, recording every interaction in a communication log, managing documents with verification and validity windows, checking a customer's financial standing and upcoming bookings before or during a conversation, sending SMS/email or placing calls from the record, and inviting customers to the self-service portal. It also reads saved fare-item templates — reusable party compositions kept against a client for quick booking.

Where it sits

Upstream, a client points at reference data owned by sibling modules: its client type (whose agent flag decides whether the client may carry a commission profile), inventory allocation categories, commission profiles, and payment terms — all surfaced here as read-only lookups. Downstream, bookings, invoices, payments, and saved fare-item templates key off the client id; archiving a client removes them from active use without orphaning that history.

Key concepts

Client — the customer hub record; status is active, inactive, or archived.
Contact — a secondary person tied to a client (emergency, billing, travelling companion).
Communication log — one timeline of every interaction: staff notes plus machine-written side-effects of real sends.
Unified file — the strategic document store; rows carry type, title, verification state, and validity dates.
Saved fare-item template (saved PAT) — a stored people-and-things composition; read-only here, written by the booking side.
Customer account — the client's portal login; created only through the invite flow.
Agent gate — a commission profile can only be held when the client's type is flagged as an agent; otherwise it is cleared automatically.
Guarded dispatch — SMS, email, and calls are real, irreversible sends gated behind preview-and-confirm.

Tools

54 tools. All writes require an explicit tenant and use preview-then-confirm guarded writes.

Reading clients and their relationships

Tool	Class	Purpose
`clients_search`	Read	Full-text search/list with type, status, VIP filters, pagination.
`clients_get`	Read	One client with the full graph: type, addresses, groups, org links, lookups resolved to names where tracked.
`clients_recent`	Read	Recently active clients.
`clients_location_filter`	Read	Find client ids by primary-address city/region/country match.
`clients_financial_summary`	Read	Derived financial summary from payment aggregates and booking money records.
`clients_invoices_list`	Read	The client's invoices with line items.
`clients_bookings_preview`	Read	Upcoming-bookings preview with total count.
`clients_saved_pats_list`	Read	The client's saved fare-item templates with their types.

Managing the client record

Tool	Class	Purpose
`clients_create`	Guarded write	Create a client; first name, last name, phone, and client type required; optional nested addresses persisted atomically.
`clients_update`	Guarded write	Update any subset of profile fields; never touches payment terms or addresses.
`clients_set_status`	Guarded write	Set status directly (`active`/`inactive`/`archived`).
`clients_archive`	Guarded write	Soft-archive (reversible status change); preferred over deletion.
`clients_set_payment_terms`	Guarded write	The only way to change payment terms — create/update never touch it.
`clients_delete`	Guarded write (destructive)	Hard-delete, irreversible; counts toward the consecutive-destructive cap.

Contacts

Tool	Class	Purpose
`clients_contacts_list`	Read	List the client's secondary contacts.
`clients_contact_create`	Guarded write	Create a contact; first name and email mandatory.
`clients_contact_update`	Guarded write	Update any subset of contact fields.
`clients_contact_delete`	Guarded write (destructive)	Hard-delete a contact.

Communication log

Tool	Class	Purpose
`clients_communications_list`	Read	Filterable history (method, direction) with total count.
`clients_communication_get`	Read	One log entry by id.
`clients_recent_communications`	Read	Recent-entries preview for a client.
`clients_communication_log`	Guarded write	Record a past interaction as a note; notes mandatory.
`clients_communication_update`	Guarded write	Edit user-settable log fields (notes, subject, transcript, priority, internal flag).
`clients_communication_record_call_outcome`	Guarded write	Write duration/recording/status onto a call's log entry.
`clients_communication_delete`	Guarded write (destructive)	Hard-delete a log entry.

Outbound messaging (real sends)

Tool	Class	Purpose
`clients_sms_send`	Guarded write	Send a real SMS; international phone format enforced, length-capped body.
`clients_email_send_templated`	Guarded write	Send one of three fixed templates (welcome, booking confirmation, document expiry).
`clients_email_send`	Guarded write	Send free-form email with subject and body.
`clients_call_make`	Guarded write	Place a backend-initiated call with a reason from a fixed set.
`clients_call_make_contextual`	Guarded write	Place a call carrying contextual payload data.
`clients_call_stop`	Guarded write	Stop an in-progress call.

Message tracking

Tool	Class	Purpose
`clients_sms_history`	Read	List the client's SMS history.
`clients_communication_history_rest`	Read	Legacy REST history view; prefer `clients_communications_list`.
`clients_call_status_get`	Read	Poll an in-flight call's status.
`clients_call_recording_get`	Read	Fetch a completed call's recording reference.

Files

Tool	Class	Purpose
`clients_files_list`	Read	Unified files with type, verification, expiry-window, and text filters.
`clients_files_by_entity`	Read	Files attached to a specific client, organisation, booking, user, or log entry.
`clients_file_get`	Read	One file row by id.
`clients_documents_list_legacy`	Read	The pre-unified legacy document table for a client.
`clients_file_presign_upload`	Read	Issue a short-lived upload URL for a document.
`clients_file_presign_download`	Read	Issue a short-lived download URL for a stored object.
`clients_s3_list`	Read	Raw object listing by prefix.
`clients_photo_access`	Read	Signed access parameters for photo content.
`clients_photo_presign`	Read	Presigned photo upload plus delivery URL.
`clients_file_register`	Guarded write	Register the catalog row after an upload completes outside the assistant.
`clients_file_update`	Guarded write	Update metadata: type, title, validity window, notes, links.
`clients_file_verify`	Guarded write	Verify or unverify a document, with optional note.
`clients_file_delete`	Guarded write (destructive)	Remove the catalog row only; the stored object is left untouched.

Lookups owned by sibling modules

Tool	Class	Purpose
`clients_types_list`	Read	Active client types.
`clients_inventory_citizens_list`	Read	Inventory allocation categories.
`clients_commission_profiles_list`	Read	Commission profiles (excluding deleted).
`clients_payment_terms_list`	Read	Payment terms.

Customer portal account

Tool	Class	Purpose
`clients_customer_account_get`	Read	Portal-account presence and derived status (none/pending/inactive/active/deleted).
`clients_customer_invite`	Guarded write	Invite a customer to the portal: creates the sign-in account and delivers a real welcome email in one step.

Rules worth knowing

Creation requires first name, last name, phone, and client type; email must be valid if supplied. Language preference accepts either a code or a display label and stores the code.
The agent gate is automatic. Setting a commission profile on a client whose type is not agent-flagged silently clears it — the preview states this rather than failing.
Payment terms have a dedicated mutation. They are never accepted on create or update, so an update cannot accidentally disturb trading terms.
Archive, don't delete. Archiving is a reversible status change; hard delete is irreversible and reserved for genuine erasure needs.
Addresses are set at creation only. Updates deliberately ignore address input — the app manages them through a separate path, and passing them inline would be rejected.
Outbound tools send to real people. Every dispatch preview states recipient and content plainly and requires confirmation; each successful send also lands an entry in the communication log server-side. Templated email is limited to the three fixed templates; free-form email has its own tool.
File bytes never cross the assistant. The flow is: request an upload URL, the human completes the transfer, then register the row. Registration omits content type (unsupported by the schema); deletion removes only the catalog entry.
Attribution is server-set. Who created or uploaded something comes from authentication, not tool arguments. The module inherits the platform-wide safety model — explicit tenant on writes, preview-before-confirm, destructive-volume cap, and sensitive values redacted from results.

Client types — owns the classification every client carries; its agent flag gates commission profiles.
Commissions — owns the commission profiles referenced by agent-type clients.
Bookings — every booking keys off a client id; also owns writing saved fare-item templates.
Gift vouchers — voucher recipients and balances surface alongside the customer relationship.