MCP tool reference - Salesfinity Docs

This page documents the Salesfinity MCP server’s tools outside the Sequencer: their parameters, what they do, and what to watch for. The Sequencer’s tools are on their own page: Sequencer tools. Each tool calls one REST API operation, linked under its name. That operation’s page is the full contract: the response shape, the errors, and the rate limit bucket it counts against. Parameter tables list exactly what the tool accepts; the Type and Required columns are the tool’s own schema.

How tools behave

These apply to every tool, on this page and on Sequencer tools.

One tool, one request. A tool sends one request to https://client-api.salesfinity.co with your API key and returns the response body as JSON text, unchanged.
Arguments are checked first. The server validates arguments against the tool’s schema before sending anything, so a missing required parameter or a value outside an enum fails without reaching the API. Arguments a tool does not list are dropped, not forwarded.
Errors come back as tool errors. A failed request returns an error whose text is Salesfinity API error: <status> - <message>, with the API’s own message, for example Salesfinity API error: 404 - Contact list not found. The errors page explains each status.
Requests time out after 60 seconds. The tool then fails with a message saying the API did not respond. For anything other than a read, the message adds that the change may still have been applied: check before calling the tool again.
Short rate limits are waited out. When the team is over its rate limit, the server waits out a Retry-After of up to 30 seconds and sends the same request once more. A longer wait, or a second 429, comes back as an error that says how many seconds to wait. The limit is per team, so other integrations on the same team use the same budget.
Only Sequencer writes are deduplicated. Each Sequencer POST, apart from the three previews, carries a new Idempotency-Key, and the automatic rate-limit retry reuses it. A tool call the assistant repeats is a new request with a new key, and writes outside the Sequencer, such as create_contact_list, carry no key at all.
Writes say who is acting. An API key identifies a team, not a person. Tools that record an author or an owner take a user_id, which must belong to a member of the team; get_team lists them.

Contact lists

These tools work on a list’s saved contacts. Each list also has a dialing queue, which is what the dialer works through. Creating a list fills both. Adding, removing and merging contacts change only the saved contacts, and reimport_contacts copies them into the queue.

get_contact_lists

List the team’s contact lists, with pagination. Returns list metadata only; use get_contact_list_by_id to see the contacts inside a list. These are the lists the other tools in this group create and edit; lists synced from a CRM integration are not included. Calls GET /v1/contact-lists/csv.

Parameter	Type	Required	Description
`search`	string	No	Case-insensitive match on the list name
`user`	string	No	Only lists owned by this user ID
`sort`	string	No	Field to sort by. Prefix with `-` for descending, e.g. `name` or `-updatedAt`. Default: `-createdAt`
`page`	number	No	Page number, 1-based. Default: 1
`limit`	number	No	Lists per page. Default: 10

get_contact_list_by_id

Get one contact list with its saved contacts. Searching, sorting and paging apply to the contacts inside the list. Calls GET /v1/contact-lists/csv/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	Contact list ID, from `get_contact_lists`
`search`	string	No	Case-insensitive match on the contact’s first name, last name, email, company or title
`sort`	string	No	Contact field to sort by, e.g. `first_name`, `-company` or `priority`. Prefix with `-` for descending
`page`	number	No	Page of contacts, 1-based. Default: 1
`limit`	number	No	Contacts per page. Default: 50

create_contact_list

Create a contact list owned by a team member, with its contacts. The new list’s dialing queue is filled at the same time, so there is no need to call reimport_contacts afterwards. Calls POST /v1/contact-lists.

Parameter	Type	Required	Description
`name`	string	Yes	List name, 1–100 characters
`user_id`	string	Yes	Team member who owns the list. Refused with 400 if they are not on the team
`contacts`	object[]	Yes	At most 2,000 contacts; send `[]` for an empty list. See Contact object

add_contact_to_list

Add one contact to a list’s saved contacts. Without tag, it reaches the dialing queue the next time you call reimport_contacts, so add every contact first and reimport once. With tag, the contact goes to the top of the list and of its dialing queue at once, with no reimport. If the list’s owner is dialing that list, it is their next call, right after the call in progress. If the list already holds the person (same email, or same phone number and first name), that contact moves to the top and takes the tag instead of a second one being added. See Call a contact next. Calls POST /v1/contact-lists/{id}.

Parameter	Type	Required	Description
`list_id`	string	Yes	Contact list ID
`tag`	string	No	A short label reps see in the dialer, e.g. `Hot lead`, up to 24 characters. Send it only for someone to call right away, like an email reply or a booked meeting
All contact fields	—	—	`first_name` is required; the rest are optional. See Contact object

remove_contact_from_list

Remove a contact from a list’s saved contacts. The dialing queue drops it the next time you call reimport_contacts. Calls DELETE /v1/contact-lists/{id}/contacts/{contactId}.

Parameter	Type	Required	Description
`list_id`	string	Yes	Contact list ID
`contact_id`	string	Yes	The contact’s `_id` inside the list, from `get_contact_list_by_id`

merge_contact_lists

Append the saved contacts of one or more source lists to a target list. Contacts are copied as they are, so duplicates are not removed, and they reach the target’s dialing queue the next time you call reimport_contacts. Calls POST /v1/contact-lists/{id}/merge.

Parameter	Type	Required	Description
`target_list_id`	string	Yes	List to merge the contacts into
`source_list_ids`	string[]	Yes	1–20 list IDs to merge from. The target’s own ID is ignored if included; if it is the only one, the call returns 404
`delete_sources`	boolean	No	Delete the source lists, and their dialing queues, after merging. Default: `false`

delete_contact_list

Permanently delete a contact list, its saved contacts and its dialing queue. This cannot be undone. Calls DELETE /v1/contact-lists/csv/{id}.

Parameter	Type	Required	Description
`list_id`	string	Yes	Contact list ID to delete

reimport_contacts

Replace a list’s dialing queue with its full set of saved contacts. Call it after adding, removing or merging contacts, or to reset a partly dialed list to its original state. Calls POST /v1/contact-lists/csv/{id}/reimport.

Parameter	Type	Required	Description
`list_id`	string	Yes	Contact list ID to reimport

Notes

Freeform notes on a person or a company. The target is matched by identifiers such as a LinkedIn URL, an email address or a website, not by contact or list IDs.

create_note

Create a note on a person or a company. If no record matches the identifiers you give, a minimal one is created and the note is attached to it. A person note needs at least one of linkedin_url, email, crm_id or phone; a company note needs website_url or name. Calls POST /v2/notes.

Parameter	Type	Required	Description
`type`	string	Yes	What the note is attached to. One of `person`, `company`
`user_id`	string	Yes	Team member writing the note. Must be on the team
`content`	string	Yes	Plain text, 1–10,000 characters
`linkedin_url`	string	No	Person only. LinkedIn profile URL; the username is extracted from it
`email`	string	No	Person only. Must be a valid email address
`crm_id`	string	No	Person only. The contact’s ID in your CRM
`phone`	string	No	Person only. Phone number in E.164 format, e.g. `+14155552671`
`company_name`	string	No	Person only. Company to link if a new contact is created; ignored when the person already exists
`company_website`	string	No	Person only. Company website to link if a new contact is created; ignored when the person already exists
`website_url`	string	No	Company only. Company website; matched on its hostname
`name`	string	No	Company only. Company name; matched case-insensitively

list_notes

List every note on a person or a company, pinned notes first, then newest first. It only reads: if no record matches the identifiers, it returns 404 rather than creating one. Takes the same identifier rules as create_note. Calls GET /v2/notes.

Parameter	Type	Required	Description
`type`	string	Yes	What to look up. One of `person`, `company`
`linkedin_url`	string	No	Person only. LinkedIn profile URL
`email`	string	No	Person only. Email address
`crm_id`	string	No	Person only. The contact’s ID in your CRM
`phone`	string	No	Person only. Phone number in E.164 format
`website_url`	string	No	Company only. Company website
`name`	string	No	Company only. Company name

update_note

Replace the text of a note. Only the note’s author may edit it; anyone else gets 403. Calls PATCH /v2/notes/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	Note ID
`content`	string	Yes	New plain text, 1–10,000 characters
`user_id`	string	Yes	Team member making the edit. Must be the note’s author

delete_note

Delete a note. Only the note’s author may delete it; anyone else gets 403. Calls DELETE /v2/notes/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	Note ID
`user_id`	string	Yes	Team member deleting the note. Must be the note’s author

toggle_pin_note

Pin a note, or unpin it if it is already pinned. Any team member may do this, not only the author. Pinned notes sort to the top of list_notes. Calls POST /v2/notes/{id}/pin.

Parameter	Type	Required	Description
`id`	string	Yes	Note ID
`user_id`	string	Yes	Team member toggling the pin. Must be on the team

Enrichment

Asynchronous phone and email lookups for a LinkedIn profile, searched across Salesfinity’s data network. A lookup that finds something costs one credit from the team’s shared balance; one that finds nothing is free. Polling a request never charges it again.

enrich_email

Start a lookup of a work or personal email address. Returns at once with a request _id and status pending; poll it with get_email_enrichment, or pass a callback_url. Costs 1 credit when an email is found. Refused with 402 when the team has no credits, so check get_enrichment_credits before a large batch. Calls POST /v1/api/enrichment/email.

Parameter	Type	Required	Description
`linkedin_url`	string	Yes	A `linkedin.com/in/<username>` profile URL, without a query string. The `https://` may be left off; the tool adds it
`type`	string	Yes	Which email to find. One of `work`, `personal`
`callback_url`	string	No	Public `http(s)` URL that receives a `POST` when the lookup finishes; localhost and private addresses are refused. Up to 3 attempts, 2 seconds apart. Polling still works
`external_id`	string	No	Up to 256 characters, echoed back in the callback only, not by this call or by polling

get_email_enrichment

Get the current state of an email lookup. Status is pending until the lookup resolves, then completed (the address is in the emails array) or not-found (emails is empty). Safe to call repeatedly; polling is never charged. Calls GET /v1/api/enrichment/email/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	The request `_id` returned by `enrich_email`

enrich_phone

Start a lookup of mobile and direct-dial numbers. Returns at once with a request _id and status pending; poll it with get_phone_enrichment, or pass a callback_url. The lookup finishes on the first number that is valid, not a landline and not graded P3. Costs 1 credit when at least one number comes back. Refused with 402 when the team has no credits. Calls POST /v1/api/enrichment/phone.

Parameter	Type	Required	Description
`linkedin_url`	string	Yes	A `linkedin.com/in/<username>` profile URL, without a query string. The `https://` may be left off; the tool adds it
`callback_url`	string	No	Public `http(s)` URL that receives a `POST` when the lookup finishes; localhost and private addresses are refused. Up to 3 attempts, 2 seconds apart. Polling still works
`external_id`	string	No	Up to 256 characters, echoed back in the callback only, not by this call or by polling

get_phone_enrichment

Get the current state of a phone lookup. Status is pending until the lookup resolves, then completed or not-found; a phone lookup never ends as failed. phone_numbers is filled only when the status is completed, and holds every number on file for the profile, each with its E.164 number, country_code, type (mobile, direct or office) and a validation object (is_valid, carrier, line_type, likely_to_answer from P1 to P3, score). Filter on validation rather than dialing every entry. Safe to call repeatedly; polling is never charged. Calls GET /v1/api/enrichment/phone/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	The request `_id` returned by `enrich_phone`

get_enrichment_credits

Get the team’s remaining enrichment credits. Email and phone lookups draw on this one balance, and enrich_email and enrich_phone are refused with 402 when it reaches zero. Calls GET /v1/api/enrichment/credits. Takes no parameters.

Team

get_team

Get the team’s name and its members. Each member’s user._id is the user ID that other tools take as user_id, user or user_ids, alongside their name, email, status and license. Takes no parameters. Calls GET /v1/team.

Call logs

get_call_logs

Search and filter the team’s call history, newest first. The tool sends every filter in the filters[...] form the operation expects. Rows leave out the transcript unless include_transcript is true; get_call_log_by_id always includes it. Calls GET /v1/call-log.

Parameter	Type	Required	Description
`page`	number	No	Page number, 1-based. Default: 1
`limit`	number	No	Calls per page, 1–100. Default: 10
`sort`	string	No	Field to sort by. Prefix with `-` for descending. Default: `-createdAt`. Ignored when `search` is set: results then come back by relevance
`start_date`	string	No	ISO 8601. Only calls at or after this time
`end_date`	string	No	ISO 8601. Only calls at or before this time
`outcome`	string	No	One of `answered`, `no-answer`, `cancelled`
`direction`	string	No	One of `inbound`, `outbound`
`min_duration`	number	No	Minimum call length in seconds
`max_duration`	number	No	Maximum call length in seconds
`has_recording`	boolean	No	Only calls with, or without, a recording
`answered_by`	string	No	Who picked up. One of `human`, `machine_start`
`is_completed`	boolean	No	`true` leaves out calls that do not count as finished: attempts the rep moved on from to dial another of the contact’s numbers, and inbound calls answered in the app that are not logged yet. `false` returns only those
`disposition_ids`	number[]	No	Numeric disposition `id` values from `get_dispositions`, e.g. `1` for a meeting set
`exclude_negative_dispositions`	boolean	No	Only calls with a positive disposition (IDs 1, 4, 6, 7 and 8). Do not combine with `disposition_ids`
`user_ids`	string[]	No	Only calls by these team members
`contact_list_ids`	string[]	No	Only calls from these contact lists
`sequences`	string[]	No	CRM sequence `id` values from `get_sequences`. Not Sequencer sequences
`from`	string[]	No	Caller phone numbers (the `from` side of the call)
`to`	string[]	No	Called phone numbers (the `to` side of the call)
`search`	string	No	Free text across the contact’s name, company, title and email, the phone numbers, and the call’s notes, summary and disposition. Transcripts are not searched
`include_transcript`	boolean	No	Include each call’s transcript. Default: `false`. Transcripts are long, so keep `limit` small

get_call_log_by_id

Get one call log, with its contact, disposition, recording, transcript and summary. Calls GET /v1/call-log/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	Call log ID

Scored calls

get_scored_calls

List AI-scored calls with their insight: the total score, a score for each facet, coaching recommendations and the call they belong to. Calls GET /v1/scored-calls.

Parameter	Type	Required	Description
`page`	number	No	Page number, 1-based. Default: 1
`limit`	number	No	Scored calls per page, 1–100. Default: 10
`sort`	string	No	Field to sort by. Prefix with `-` for descending. Default: `-createdAt`
`start_date`	string	No	The earliest `createdAt` to include (ISO 8601)
`end_date`	string	No	The latest `createdAt` to include (ISO 8601)
`min_score`	number	No	The lowest `insight.total_score` to include, 0–100
`max_score`	number	No	The highest `insight.total_score` to include, 0–100
`user_id`	string	No	Only calls by this team member

get_scored_call_by_id

Get one scored call with its full AI insight, facet scores and recommendations. Calls GET /v1/scored-calls/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	Scored call ID

Dispositions

get_dispositions

Get the call dispositions available to the team, default and custom. Each one’s numeric id is the value get_call_logs and the analytics tools filter on. Calls GET /v1/dispositions.

Parameter	Type	Required	Description
`is_custom`	boolean	No	`true` returns only custom dispositions, `false` only default ones
`category`	string	No	One of `positive`, `negative`, `neutral`, `not_answered`, `cancelled`

get_disposition_by_id

Get one disposition. Calls GET /v1/dispositions/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	The disposition’s numeric `id`, e.g. `12`, not its `_id`

CRM sequences

These are the sequence names seen on the team’s call logs, from an external CRM or sales engagement platform. They are not the Salesfinity Sequencer, which has its own tools.

get_sequences

List the CRM sequences seen on the team’s call logs, with how often and how recently each was used. Each one’s id is the value get_call_logs takes in sequences. Calls GET /v1/sequences.

Parameter	Type	Required	Description
`search`	string	No	Case-insensitive match on the sequence name
`sort`	string	No	One of `-last_used_at`, `last_used_at`, `-total_calls`, `total_calls`, `-name`, `name`. Default: `-last_used_at`
`page`	number	No	Page number, 1-based. Default: 1
`limit`	number	No	Sequences per page, 1–100. Default: 100

get_sequence_by_id

Get one CRM sequence. Calls GET /v1/sequences/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	The sequence `id` from `get_sequences`

Snoozed contacts

get_snoozed_contacts

List snoozed contacts, each with the team member it belongs to and its snooze_until date. Calls GET /v1/snoozed-contacts.

Parameter	Type	Required	Description
`page`	number	No	Page number, 1-based. Default: 1
`limit`	number	No	Contacts per page, 1–100. Default: 10
`sort`	string	No	Field to sort by. Prefix with `-` for descending. Default: `-createdAt`
`linkedin_username`	string	No	Only this LinkedIn username
`external_contact_id`	string	No	Only this CRM contact ID
`email`	string	No	Only this email address
`phone_number`	string	No	Only this phone number

get_snoozed_contact_by_id

Get one snoozed contact by its ID. Calls GET /v1/snoozed-contacts/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	Snoozed contact ID

get_snoozed_contact_by_linkedin

Look up a snoozed contact by LinkedIn username. Its _id is the ID the other snooze tools take. Calls GET /v1/snoozed-contacts/by-linkedin/{username}.

Parameter	Type	Required	Description
`username`	string	Yes	The LinkedIn username, the part after `linkedin.com/in/`, not a full URL

update_snoozed_contact

Change the identifiers stored on a snooze record, or move the date it ends with snooze_until. To end a snooze now, use delete_snoozed_contact. Calls PUT /v1/snoozed-contacts/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	Snoozed contact ID
`linkedin_username`	string	No	LinkedIn username
`external_contact_id`	string	No	CRM contact ID
`email`	string	No	Email address
`phone_number`	string	No	Phone number
`snooze_until`	string	No	Currently rejected with 400, whatever its format

delete_snoozed_contact

Delete a snooze record. Lists imported into the dialer afterwards no longer mark the contact as snoozed; a list already imported keeps the marking until it is imported again. Calls DELETE /v1/snoozed-contacts/{id}.

Parameter	Type	Required	Description
`id`	string	Yes	Snoozed contact ID

Follow-up tasks

get_follow_ups

List the team’s follow-up tasks, each with its contact, priority, follow_up_date and whether it is overdue. Calls GET /v1/follow-up.

Parameter	Type	Required	Description
`page`	number	No	Page number, 1-based. Default: 1
`limit`	number	No	Tasks per page, 1–100. Default: 10
`sort`	string	No	Field to sort by. Prefix with `-` for descending. Default: `-createdAt`

Custom fields

get_custom_fields

Get the team’s custom field mappings: for each connected source, how its fields map to the names Salesfinity shows (internal_name). Contact custom_fields are free text; to match the fields a CRM import creates, use a mapping’s internal_name as the label. Takes no parameters. Calls GET /v1/custom-fields.

Analytics

The three analytics tools count whole UTC days: start_date runs from 00:00 UTC on its date and end_date to the end of its date. Results are cached for up to 5 minutes.

get_analytics_overview

Get the team’s totals for a period, such as calls, connected calls, conversations and meetings set, each with its growth rate against the previous period of the same length. Calls GET /v1/analytics/overview.

Parameter	Type	Required	Description
`start_date`	string	Yes	First day, as `YYYY-MM-DD`. A date and time is accepted, but it is converted to UTC and only the date is kept
`end_date`	string	Yes	Last day, as `YYYY-MM-DD`, included to the end of the day. A date and time is accepted, but it is converted to UTC and only the date is kept
`user_ids`	string[]	No	Only these team members
`disposition_ids`	string[]	No	Numeric disposition `id` values from `get_dispositions`, sent as strings, e.g. `"1"`

get_list_performance

Get the same metrics broken down by contact list. Calls GET /v1/analytics/list-performance.

Parameter	Type	Required	Description
`start_date`	string	Yes	First day, as `YYYY-MM-DD`. A date and time is accepted, but it is converted to UTC and only the date is kept
`end_date`	string	Yes	Last day, as `YYYY-MM-DD`, included to the end of the day. A date and time is accepted, but it is converted to UTC and only the date is kept
`user_ids`	string[]	No	Only these team members
`disposition_ids`	string[]	No	Numeric disposition `id` values from `get_dispositions`, sent as strings, e.g. `"1"`
`page`	number	No	Page number, 1-based. Default: 1
`limit`	number	No	Lists per page, 1–100. Default: 10
`search`	string	No	Match on the list name

get_sdr_performance

Get the same metrics broken down by SDR. Calls GET /v1/analytics/sdr-performance.

Parameter	Type	Required	Description
`start_date`	string	Yes	First day, as `YYYY-MM-DD`. A date and time is accepted, but it is converted to UTC and only the date is kept
`end_date`	string	Yes	Last day, as `YYYY-MM-DD`, included to the end of the day. A date and time is accepted, but it is converted to UTC and only the date is kept
`user_ids`	string[]	No	Only these team members
`disposition_ids`	string[]	No	Numeric disposition `id` values from `get_dispositions`, sent as strings, e.g. `"1"`
`page`	number	No	Page number, 1-based. Default: 1
`limit`	number	No	SDRs per page, 1–100. Default: 10
`search`	string	No	Match on the SDR’s name or email

Contact object

The fields create_contact_list takes for each contact and add_contact_to_list takes directly. Length limits are enforced by the API.

Field	Type	Required	Description
`first_name`	string	Yes	First name, up to 200 characters
`last_name`	string	No	Last name, up to 200 characters
`email`	string	No	Email address, up to 320 characters
`phone_numbers`	object[]	No	Up to 10. Each has `type` (one of `mobile`, `direct`, `office`), `number` (E.164, e.g. `+14155552671`), and optional `country_code` (ISO 3166-1 alpha-2, e.g. `US`) and `extension`
`company`	string	No	Company name, up to 300 characters
`title`	string	No	Job title, up to 300 characters
`linkedin`	string	No	LinkedIn profile URL, up to 500 characters
`website`	string	No	Website URL, up to 500 characters
`notes`	string	No	Notes, up to 2,000 characters
`priority`	number	No	Dialing priority; a lower number is a higher priority
`timezone`	string	No	IANA timezone, e.g. `America/New_York`, up to 100 characters
`custom_fields`	object[]	No	Up to 10. Each has `type` (one of `string`, `number`, `boolean`), `label` (up to 100 characters; see `get_custom_fields`) and an optional `value` (a string, number, boolean or array of strings)

​How tools behave

​Contact lists

​get_contact_lists

​get_contact_list_by_id

​create_contact_list

​add_contact_to_list

​remove_contact_from_list

​merge_contact_lists

​delete_contact_list

​reimport_contacts

​Notes

​create_note

​list_notes

​update_note

​delete_note

​toggle_pin_note

​Enrichment

​enrich_email

​get_email_enrichment

​enrich_phone

​get_phone_enrichment

​get_enrichment_credits

​Team

​get_team

​Call logs

​get_call_logs

​get_call_log_by_id

​Scored calls

​get_scored_calls

​get_scored_call_by_id

​Dispositions

​get_dispositions

​get_disposition_by_id

​CRM sequences

​get_sequences

​get_sequence_by_id

​Snoozed contacts

​get_snoozed_contacts

​get_snoozed_contact_by_id

​get_snoozed_contact_by_linkedin

​update_snoozed_contact

​delete_snoozed_contact

​Follow-up tasks

​get_follow_ups

​Custom fields

​get_custom_fields

​Analytics

​get_analytics_overview

​get_list_performance

​get_sdr_performance

​Contact object

​Next steps

Sequencer tools

Browse use cases