Menu

Mattering Sales MCP tools

35 tools on the Mattering MCP gateway at https://mcp.mattering.io/mcp. Each call forwards your token to the Sales User API, so a tool can do exactly what your key can do.

Connect any MCP client to https://mcp.mattering.io/mcp; it discovers the Mattering sign-in and asks you to approve the tools it may use. Tool names, parameters and descriptions below are read from the gateway source. See the MCP gateway concept page for connection details.

Activity

sales_list_activities

Read the activity timeline (emails, calls, notes, field changes), newest first.

Full description

Read the activity timeline (emails, calls, notes, field changes), newest first.

Required: space_id. Anchor with contact_id, business_id or deal_id; narrow by type or a created_after / created_before window (applied to when it happened).

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
deal_idOptional[str]optionalnone
typeOptional[str]optionalnone
created_afterOptional[str]optionalnone
created_beforeOptional[str]optionalnone
limitOptional[int]optionalnone

Calls

sales_log_activity

Add an entry to a contact's, business's or deal's timeline.

Full description

Add an entry to a contact's, business's or deal's timeline.

Required: type (note, call, meeting, email_out, email_in, sms_out, sms_in, custom), one of contact_id / business_id / deal_id, and a subject or body_text. occurred_at (ISO) defaults to now. Pass idempotency_key when retrying so it is logged once.

Parameters

NameTypeRequiredDefault
typestrrequirednone
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
deal_idOptional[str]optionalnone
subjectOptional[str]optionalnone
body_textOptional[str]optionalnone
occurred_atOptional[str]optionalnone
idempotency_keyOptional[str]optionalnone

Calls

Businesses

sales_create_business

Create a business (account / company) in a CRM space.

Full description

Create a business (account / company) in a CRM space.

Required: space_id, name. Optional: domain, industry, website, phone, email, description (notes), lifecycle_stage, status, source, address fields, tags, owner_email (a seated workspace member; defaults to you) and custom_fields ({field key or name: value}). To avoid duplicates when you might be re-creating one, use sales_upsert_business.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
namestrrequirednone
domainOptional[str]optionalnone
industryOptional[str]optionalnone
websiteOptional[str]optionalnone
phoneOptional[str]optionalnone
emailOptional[str]optionalnone
descriptionOptional[str]optionalnone
lifecycle_stageOptional[str]optionalnone
statusOptional[str]optionalnone
sourceOptional[str]optionalnone
address_line1Optional[str]optionalnone
address_line2Optional[str]optionalnone
cityOptional[str]optionalnone
stateOptional[str]optionalnone
postal_codeOptional[str]optionalnone
countryOptional[str]optionalnone
tagsOptional[list[str]]optionalnone
owner_emailOptional[str]optionalnone
custom_fieldsOptional[dict[str, Any]]optionalnone

Calls

sales_delete_business

Archive a business (soft delete; ``sales_update_business`` with

Full description

Archive a business (soft delete; sales_update_business with restore=True brings it back). Its contacts are kept.

Parameters

NameTypeRequiredDefault
business_idstrrequirednone

Calls

sales_list_businesses

List businesses (accounts / companies) in a CRM space, one page at a time.

Full description

List businesses (accounts / companies) in a CRM space, one page at a time.

Required: space_id. Filters: keyword (name or domain contains), domain (exact; https://www.acme.com/x matches acme.com), industry, lifecycle_stage, status, owner_email, tag, updated_after (ISO date/datetime), include_archived. sort: name (default), created_at, updated_at; prefix - for descending. Paging: limit (default 100, max 500) and offset; the response meta has total, has_more and next_offset.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
keywordOptional[str]optionalnone
domainOptional[str]optionalnone
industryOptional[str]optionalnone
lifecycle_stageOptional[str]optionalnone
statusOptional[str]optionalnone
owner_emailOptional[str]optionalnone
tagOptional[str]optionalnone
updated_afterOptional[str]optionalnone
include_archivedOptional[bool]optionalnone
sortOptional[str]optionalnone
limitOptional[int]optionalnone
offsetOptional[int]optionalnone

Calls

sales_merge_businesses

Merge duplicate businesses into one. Confirm which to keep with the user first.

Full description

Merge duplicate businesses into one. Confirm which to keep with the user first.

primary_id survives; up to 10 duplicate_ids are merged into it: their contacts, deals, activity, notes, tasks, meetings, files and logged email move over, empty fields are filled from the duplicates, and the duplicates are archived (restorable).

Parameters

NameTypeRequiredDefault
primary_idstrrequirednone
duplicate_idslist[str]requirednone

Calls

sales_save_businesses_bulk

Create, update or upsert up to 100 businesses in one call.

Full description

Create, update or upsert up to 100 businesses in one call.

Prefer this over looping sales_create_business / sales_update_business. mode: create (default), update (every record needs id) or upsert (match on domain, else name). Each record takes the same keys as sales_create_business. Rows are independent: the response lists each row's status (created | updated | error) with its id or error, and meta counts them.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
recordslist[dict[str, Any]]requirednone
modeOptional[str]optionalnone

Calls

sales_update_business

Update a business. Only the arguments you pass change.

Full description

Update a business. Only the arguments you pass change.

Required: business_id. To clear a text field pass ""; tags REPLACES the list (pass [] to clear); owner_email "" unassigns; restore=True un-archives; custom_fields merges ({key: value}, null clears one).

Parameters

NameTypeRequiredDefault
business_idstrrequirednone
nameOptional[str]optionalnone
domainOptional[str]optionalnone
industryOptional[str]optionalnone
websiteOptional[str]optionalnone
phoneOptional[str]optionalnone
emailOptional[str]optionalnone
notesOptional[str]optionalnone
lifecycle_stageOptional[str]optionalnone
statusOptional[str]optionalnone
sourceOptional[str]optionalnone
address_line1Optional[str]optionalnone
address_line2Optional[str]optionalnone
cityOptional[str]optionalnone
stateOptional[str]optionalnone
postal_codeOptional[str]optionalnone
countryOptional[str]optionalnone
tagsOptional[list[str]]optionalnone
owner_emailOptional[str]optionalnone
restoreOptional[bool]optionalnone
custom_fieldsOptional[dict[str, Any]]optionalnone

Calls

sales_upsert_business

Create a business, or update the one that already matches.

Full description

Create a business, or update the one that already matches.

Matches on domain (normalized) when given, else name (case-insensitive); force one with match_on. A match updates only the fields you pass. Returns created: true|false. Two live matches is an ambiguous_match error: update one by id instead.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
nameOptional[str]optionalnone
domainOptional[str]optionalnone
match_onOptional[str]optionalnone
industryOptional[str]optionalnone
websiteOptional[str]optionalnone
phoneOptional[str]optionalnone
emailOptional[str]optionalnone
notesOptional[str]optionalnone
lifecycle_stageOptional[str]optionalnone
statusOptional[str]optionalnone
tagsOptional[list[str]]optionalnone
owner_emailOptional[str]optionalnone
custom_fieldsOptional[dict[str, Any]]optionalnone

Calls

Contacts

sales_create_contact

Create a contact (person) in a CRM space.

Full description

Create a contact (person) in a CRM space.

Required: space_id, first_name, last_name. Optional: email, business_id (link to a business; unknown ids are an error), phone, title, lifecycle_stage, status, notes, tags, owner_email (a seated workspace member; defaults to you), persona_id and custom_fields ({field key or name: value}). If the person may already exist, use sales_upsert_contact (matches on email) instead.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
first_namestrrequirednone
last_namestrrequirednone
emailOptional[str]optionalnone
business_idOptional[str]optionalnone
phoneOptional[str]optionalnone
titleOptional[str]optionalnone
lifecycle_stageOptional[str]optionalnone
statusOptional[str]optionalnone
notesOptional[str]optionalnone
tagsOptional[list[str]]optionalnone
owner_emailOptional[str]optionalnone
persona_idOptional[str]optionalnone
custom_fieldsOptional[dict[str, Any]]optionalnone

Calls

sales_delete_contact

Archive a contact (soft delete; ``sales_update_contact`` with

Full description

Archive a contact (soft delete; sales_update_contact with restore=True brings it back). Their history is kept.

Parameters

NameTypeRequiredDefault
contact_idstrrequirednone

Calls

sales_get_contact

Get a single contact by id: fields, owner, persona, tags, notes and

Full description

Get a single contact by id: fields, owner, persona, tags, notes and custom field values.

Parameters

NameTypeRequiredDefault
contact_idstrrequirednone

Calls

sales_list_contacts

List contacts (people) in a CRM space, one page at a time.

Full description

List contacts (people) in a CRM space, one page at a time.

Required: space_id. Filters: business_id, keyword (name, email or phone contains), email (exact), lifecycle_stage, status, owner_email, persona_id, tag, updated_after (ISO date/datetime), include_archived. sort: name (default), email, created_at, updated_at; - for descending. Paging: limit (default 100, max 500) and offset; meta has total, has_more and next_offset.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
business_idOptional[str]optionalnone
keywordOptional[str]optionalnone
emailOptional[str]optionalnone
lifecycle_stageOptional[str]optionalnone
statusOptional[str]optionalnone
owner_emailOptional[str]optionalnone
persona_idOptional[str]optionalnone
tagOptional[str]optionalnone
updated_afterOptional[str]optionalnone
include_archivedOptional[bool]optionalnone
sortOptional[str]optionalnone
limitOptional[int]optionalnone
offsetOptional[int]optionalnone

Calls

sales_list_custom_fields

List custom field definitions (key, name, type, options).

Full description

List custom field definitions (key, name, type, options).

Required: record_type (business, contact or deal); deal fields are per pipeline, so deal also needs pipe_id. Write values through custom_fields on the create/update tools, keyed by a field's key or name.

Parameters

NameTypeRequiredDefault
record_typestrrequirednone
pipe_idOptional[str]optionalnone

Calls

sales_list_personas

List the space's personas (ideal-customer profiles) to assign with

Full description

List the space's personas (ideal-customer profiles) to assign with persona_id on a contact. Required: space_id.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
keywordOptional[str]optionalnone
limitOptional[int]optionalnone

Calls

sales_merge_contacts

Merge duplicate contacts into one. Confirm which to keep with the user first.

Full description

Merge duplicate contacts into one. Confirm which to keep with the user first.

primary_id is the contact that survives; up to 10 duplicate_ids are merged into it: their activity, notes, tasks, meetings, files, deals, logged email and campaign membership move over, the survivor's empty fields are filled from the duplicates (its own values are kept), tags are combined, and the duplicates are archived (restorable).

Parameters

NameTypeRequiredDefault
primary_idstrrequirednone
duplicate_idslist[str]requirednone

Calls

sales_save_contacts_bulk

Create, update or upsert up to 100 contacts in one call.

Full description

Create, update or upsert up to 100 contacts in one call.

Prefer this over looping sales_create_contact / sales_update_contact. mode: create (default), update (every record needs id) or upsert (match on email). Each record takes the same keys as sales_create_contact. Rows are independent: the response lists each row's status (created | updated | error) with its id or error, and meta counts them.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
recordslist[dict[str, Any]]requirednone
modeOptional[str]optionalnone

Calls

sales_update_contact

Update a contact. Only the arguments you pass change.

Full description

Update a contact. Only the arguments you pass change.

Required: contact_id. To clear a text field pass ""; business_id "" detaches it; tags REPLACES the list ([] clears); owner_email "" unassigns; persona_id "" clears; restore=True un-archives; custom_fields merges ({key: value}, null clears one).

Parameters

NameTypeRequiredDefault
contact_idstrrequirednone
first_nameOptional[str]optionalnone
last_nameOptional[str]optionalnone
emailOptional[str]optionalnone
phoneOptional[str]optionalnone
titleOptional[str]optionalnone
business_idOptional[str]optionalnone
lifecycle_stageOptional[str]optionalnone
statusOptional[str]optionalnone
notesOptional[str]optionalnone
tagsOptional[list[str]]optionalnone
owner_emailOptional[str]optionalnone
persona_idOptional[str]optionalnone
restoreOptional[bool]optionalnone
custom_fieldsOptional[dict[str, Any]]optionalnone

Calls

sales_upsert_contact

Create a contact, or update the one with this email.

Full description

Create a contact, or update the one with this email.

Matches on email (case-insensitive). A match updates only the fields you pass. Returns created: true|false. Two live contacts with the email is an ambiguous_match error: update one by id.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
emailstrrequirednone
first_nameOptional[str]optionalnone
last_nameOptional[str]optionalnone
phoneOptional[str]optionalnone
titleOptional[str]optionalnone
business_idOptional[str]optionalnone
lifecycle_stageOptional[str]optionalnone
statusOptional[str]optionalnone
notesOptional[str]optionalnone
tagsOptional[list[str]]optionalnone
owner_emailOptional[str]optionalnone
persona_idOptional[str]optionalnone
custom_fieldsOptional[dict[str, Any]]optionalnone

Calls

Deals

sales_create_deal

Create a deal (opportunity) in a sales pipeline.

Full description

Create a deal (opportunity) in a sales pipeline.

Required: space_id, pipe_id, name. Optional: value (monetary amount) and stage (stage name within the pipeline; defaults to the pipeline's first stage server-side when omitted).

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
pipe_idstrrequirednone
namestrrequirednone
valueOptional[float]optionalnone
stageOptional[str]optionalnone

Calls

sales_list_deals

List deals (opportunities) in a CRM space, newest first.

Full description

List deals (opportunities) in a CRM space, newest first.

Required: space_id. Optional: pipe_id, contact_id (deals where they are the primary contact), business_id. Paging: limit (max 200), offset.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone
pipe_idOptional[str]optionalnone
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
limitOptional[int]optionalnone
offsetOptional[int]optionalnone

Calls

Diagnostics

sales_list_capabilities

List the sales service's registered capabilities (debug helper).

Full description

List the sales service's registered capabilities (debug helper).

Returns the available capability names, HTTP methods, paths, categories, and required / optional parameter lists. Useful for discovering what the service exposes without paging through the docs.

Takes no parameters.

Files

sales_finish_file_upload

Finish an upload started with ``sales_start_file_upload``: attaches

Full description

Finish an upload started with sales_start_file_upload: attaches the uploaded file to the contact or business. Pass the same contact_id / business_id. Safe to retry if it fails.

Parameters

NameTypeRequiredDefault
upload_idstrrequirednone
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
filenameOptional[str]optionalnone
titleOptional[str]optionalnone
document_typeOptional[str]optionalnone
is_privateOptional[bool]optionalnone

Calls

sales_list_files

List files on a contact or business (or a whole space), newest first.

Full description

List files on a contact or business (or a whole space), newest first.

Pass one of contact_id, business_id or space_id. Returns metadata (title, filename, size, type); private files only to their uploader.

Parameters

NameTypeRequiredDefault
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
space_idOptional[str]optionalnone
document_typeOptional[str]optionalnone
limitOptional[int]optionalnone
offsetOptional[int]optionalnone

Calls

sales_manage_file

Update a file's details or delete it.

Full description

Update a file's details or delete it.

action="update": pass only what changes (document_type is contract, proposal, invoice, receipt, agreement, presentation, report or other). action="delete" removes the file permanently.

Parameters

NameTypeRequiredDefault
actionstrrequirednone
file_idstrrequirednone
titleOptional[str]optionalnone
descriptionOptional[str]optionalnone
document_typeOptional[str]optionalnone
is_privateOptional[bool]optionalnone
tagsOptional[list[str]]optionalnone

Calls

sales_start_file_upload

Start uploading a file to a contact or business (any size up to 5 GB).

Full description

Start uploading a file to a contact or business (any size up to 5 GB).

Returns upload_url and upload_id: PUT the raw bytes to upload_url with the returned Content-Type header, then call sales_finish_file_upload with the upload_id. If it answers mode: "multipart", direct uploads are off on this server.

Parameters

NameTypeRequiredDefault
filenamestrrequirednone
file_sizeintrequirednone
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
content_typeOptional[str]optionalnone

Calls

Meetings

sales_list_meetings

List meetings with a contact or business (or a whole space), soonest first.

Full description

List meetings with a contact or business (or a whole space), soonest first.

Pass one of contact_id, business_id or space_id. Canceled meetings are left out unless status="canceled". Window with start_after / start_before (ISO).

Parameters

NameTypeRequiredDefault
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
space_idOptional[str]optionalnone
statusOptional[str]optionalnone
start_afterOptional[str]optionalnone
start_beforeOptional[str]optionalnone
limitOptional[int]optionalnone
offsetOptional[int]optionalnone

Calls

sales_manage_meeting

Schedule, update or cancel a meeting with a contact or business.

Full description

Schedule, update or cancel a meeting with a contact or business.

Meetings live in Mattering Calendar on your calendar. action="create": requires title, start_at, end_at (ISO datetimes with an offset) and contact_id or business_id; optional description, location, meeting_url, is_all_day. action="update": requires meeting_id; pass only what changes. action="cancel": requires meeting_id.

Parameters

NameTypeRequiredDefault
actionstrrequirednone
meeting_idOptional[str]optionalnone
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
titleOptional[str]optionalnone
start_atOptional[str]optionalnone
end_atOptional[str]optionalnone
descriptionOptional[str]optionalnone
locationOptional[str]optionalnone
meeting_urlOptional[str]optionalnone
is_all_dayOptional[bool]optionalnone
statusOptional[str]optionalnone

Calls

  • POST/api/user/v1/meetings/
  • PATCH/api/user/v1/meetings/{meeting_id}/
  • DELETE/api/user/v1/meetings/{meeting_id}/

Notes and tasks

sales_list_notes

List notes on a contact or business (or a whole space), newest first.

Full description

List notes on a contact or business (or a whole space), newest first.

Pass one of contact_id, business_id or space_id. Private notes are only returned to their author. Paging: limit (default 50, max 200), offset.

Parameters

NameTypeRequiredDefault
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
space_idOptional[str]optionalnone
limitOptional[int]optionalnone
offsetOptional[int]optionalnone

Calls

sales_list_tasks

List CRM tasks on a contact or business (or a whole space), by due date.

Full description

List CRM tasks on a contact or business (or a whole space), by due date.

Pass one of contact_id, business_id or space_id. Filters: status (pending, in_progress, completed, cancelled; comma-separate several), assigned_to_email, overdue (past due and not done), due_before / due_after. Paging: limit (default 50, max 200), offset.

Parameters

NameTypeRequiredDefault
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
space_idOptional[str]optionalnone
statusOptional[str]optionalnone
assigned_to_emailOptional[str]optionalnone
overdueOptional[bool]optionalnone
due_beforeOptional[str]optionalnone
due_afterOptional[str]optionalnone
limitOptional[int]optionalnone
offsetOptional[int]optionalnone

Calls

sales_manage_note

Create, update or delete a note on a contact or business.

Full description

Create, update or delete a note on a contact or business.

action="create": requires content and contact_id or business_id; optional title (defaults to the first line), is_private, tags. action="update": requires note_id; pass only what changes. action="delete": requires note_id.

Parameters

NameTypeRequiredDefault
actionstrrequirednone
note_idOptional[str]optionalnone
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
titleOptional[str]optionalnone
contentOptional[str]optionalnone
is_privateOptional[bool]optionalnone
tagsOptional[list[str]]optionalnone

Calls

sales_manage_task

Create, update or delete a CRM task on a contact or business.

Full description

Create, update or delete a CRM task on a contact or business.

action="create": requires title and contact_id or business_id; optional description, status (pending, in_progress, completed, cancelled), priority (low, medium, high, urgent), due_date (ISO), assigned_to_email (a seated workspace member), tags. action="update": requires task_id; pass only what changes (status="completed" completes it; due_date="" clears it). action="delete": requires task_id.

Parameters

NameTypeRequiredDefault
actionstrrequirednone
task_idOptional[str]optionalnone
contact_idOptional[str]optionalnone
business_idOptional[str]optionalnone
titleOptional[str]optionalnone
descriptionOptional[str]optionalnone
statusOptional[str]optionalnone
priorityOptional[str]optionalnone
due_dateOptional[str]optionalnone
assigned_to_emailOptional[str]optionalnone
tagsOptional[list[str]]optionalnone

Calls

Sales Pipelines

sales_list_pipes

List sales pipelines in a CRM space, with their stages.

Full description

List sales pipelines in a CRM space, with their stages.

Required: space_id.

Parameters

NameTypeRequiredDefault
space_idstrrequirednone

Calls

Spaces

sales_list_my_spaces

List CRM spaces accessible to the current user (counts, role, names).

Full description

List CRM spaces accessible to the current user (counts, role, names).

Empty results are annotated with the resolved identity so an empty list can be told apart from an identity mismatch.

Takes no parameters.

Calls

Identity tools (every app)

The gateway registers these once, outside any app family. Call whoami first when a result looks empty.

auth_statusReport token health, expiry, bound principal, and catalog version.
get_accountReturn the current user's account profile (email, name, id).
get_organizationReturn the organization this session is currently acting as.
list_organizationsList every organization the authenticated identity belongs to.
reauthenticateExplain how to refresh this connection's authentication.
switch_accountExplain how to re-authenticate as a different account / org.
whoamiShow who this MCP session is authenticated as.
Start Free Explore our Products