How do I use Salesmate MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Salesmate MCP Server search contacts for Acme Corp" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Salesmate MCP Server

by arnav-chauhan-kgpian

Overview Schema Source Related Servers Discussions Admin

Python

Remote

Salesmate MCP Server

A production-ready Model Context Protocol (MCP) server that exposes the Salesmate CRM to Claude Desktop (and any other MCP client). Built with FastMCP, HTTPX, Pydantic, and python-dotenv.

It lets Claude search contacts, inspect and update deals, create tasks and notes, and review recent activity — all through clean, typed, validated tools.

Get started

There are two ways to install. Pick one.

Option A - One-click install (`.mcpb`, no terminal)

The cleanest end-user experience. Anyone can install with no clone, no virtualenv, no JSON editing - just a click and a form.

Download the .mcpb bundle for your platform from the project's GitHub Releases page (or build it yourself - see below).
In Claude Desktop, go to Settings -> Extensions -> Install Extension... and pick the .mcpb file.
When prompted, enter:
- Salesmate Session Key (the field is masked; stored in your OS keychain).
- Salesmate Workspace URL, e.g. https://yourcompany.salesmate.io.
Done. No restart needed - the salesmate tools appear in the tool picker.

Use the Session Key. Salesmate shows three keys - Access Key, Secret Key, and Session Key (Setup -> Integrations -> API & Webhooks). The v4 API used here authenticates with the Session Key; the other two return AuthorizationFailed.

Build the bundle yourself

The .mcpb is platform-specific (Python wheels contain compiled binaries), so build it on the OS you'll install it on:

git clone https://github.com/arnav-chauhan-kgpian/salesmate-mcp.git
cd salesmate-mcp
python -m venv .venv
# Windows:  .\.venv\Scripts\activate     macOS/Linux:  source .venv/bin/activate
pip install -e .
python build_mcpb.py
# Output: dist/salesmate-mcp-<platform>-py<ver>.mcpb

Then install the resulting .mcpb as in step 2 above.

Option B - Clone & connect (manual)

A new user with no copy of the code connects in four steps:

# 1. Clone the repo
git clone https://github.com/arnav-chauhan-kgpian/salesmate-mcp.git
cd salesmate-mcp

# 2. Create a virtualenv and install
python -m venv .venv
# Windows:  .\.venv\Scripts\activate     macOS/Linux:  source .venv/bin/activate
pip install -e .

# 3. Connect to Claude Desktop (writes .env + Claude config, verifies live)
python setup_salesmate.py --verify

# 4. Fully quit and reopen Claude Desktop

You must provide your own secrets

This repository ships no credentials. Every user supplies their own Salesmate keys once. The setup_salesmate.py script will prompt for them and write them into a local .env file (which is git-ignored and never committed):

SALESMATE_API_KEY=<your Salesmate SESSION KEY>
SALESMATE_BASE_URL=https://yourcompany.salesmate.io

You can also create this .env by hand (copy .env.example to .env and fill it in) instead of letting the script prompt you — then run python setup_salesmate.py --no-input --verify.

Use the Session Key. Salesmate shows three keys — Access Key, Secret Key, and Session Key (Setup → Integrations → API & Webhooks). The v4 API used here authenticates with the Session Key; the other two return AuthorizationFailed.

The setup script:

Collects your Session Key + workspace URL (or reuses an existing .env).
Writes them to .env.
Registers the salesmate server in your Claude Desktop config — preserving any servers you already have, with a .bak backup. No secrets are written into the Claude config; the server reads them from your .env.
With --verify, runs a live read-only check so you know it works before opening Claude.

Non-interactive form (e.g. for scripted installs):

python setup_salesmate.py --api-key <SESSION_KEY> --base-url https://yourcompany.salesmate.io --verify

Related MCP server: MCP-Server

Features

🔌 8 MCP tools covering contacts, deals, tasks, notes and activities.
🧱 Modular architecture — config, client, models and exceptions are cleanly separated; each tool group lives in its own module.
🔁 Resilient HTTP client — async HTTPX with a 30s timeout, automatic retries and exponential backoff (honouring Retry-After) for transient 429/5xx/network failures.
🧪 Typed Pydantic models for every resource; structured JSON is always returned — never raw HTTP responses.
🛡️ Robust error handling — every failure is mapped to a structured error object (SalesmateAuthError, SalesmateNotFoundError, ...).
🪵 Structured logging to stderr (stdout is reserved for the MCP transport).
✅ Full unit-test suite covering every tool and the HTTP client.

Tools

Tool	Signature	Description
`search_contacts`	`(query: str)`	Search contacts by name, email or company.
`get_contact`	`(contact_id: int)`	Fetch a contact's full details.
`list_deals`	`(contact_id: int \| None)`	List deals, optionally for one contact.
`get_deal`	`(deal_id: int)`	Fetch a deal's full details.
`update_deal_stage`	`(deal_id: int, stage: str)`	Move a deal to a new stage.
`create_task`	`(title: str, due_date: str, contact_id: int \| None)`	Create a task.
`create_note`	`(contact_id: int, note: str)`	Attach a note to a contact.
`get_recent_activities`	`(contact_id: int)`	Recent activities for a contact.

Every tool returns a JSON object. On success the payload contains "ok": true plus the requested data; on failure it contains "error": true with a type and message (and status_code for API errors).

Project structure

salesmate-mcp/
├── server.py                         # FastMCP entrypoint
├── salesmate/
│   ├── __init__.py
│   ├── config.py                     # env loading + validation
│   ├── client.py                     # async HTTPX client (retries, errors)
│   ├── models.py                     # Pydantic response models
│   └── exceptions.py                 # exception hierarchy
├── tools/
│   ├── __init__.py                   # registration + error mapping
│   ├── contacts.py
│   ├── deals.py
│   ├── tasks.py
│   ├── notes.py
│   └── activities.py
├── tests/                            # pytest suite (tools + client + config)
├── .env.example
├── pyproject.toml
├── README.md
└── claude_desktop_config_example.json

Installation

1. Prerequisites

Python 3.12+
A Salesmate account with an API Session Key (Setup → Integrations → API & Webhooks). Salesmate shows three keys — Access Key, Secret Key and Session Key — and the v4 API used here authenticates with the Session Key.

2. Get the code

cd salesmate-mcp

3. Create and activate a virtual environment

macOS / Linux:

python3.12 -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1

4. Install dependencies

# runtime only
pip install -e .

# runtime + dev/test tools
pip install -e ".[dev]"

Prefer not to install the project as a package? You can instead run: pip install mcp httpx pydantic python-dotenv

5. Configure environment variables

Copy the example file and fill in your credentials:

macOS / Linux:

cp .env.example .env

Windows (PowerShell):

Copy-Item .env.example .env

Then edit .env:

SALESMATE_API_KEY=your-salesmate-access-token
SALESMATE_BASE_URL=https://yourcompany.salesmate.io

All other variables are optional — see .env.example for the full list.

6. Run the server

python server.py

The server communicates over stdio. When launched manually it will simply wait for an MCP client to connect; logs are printed to stderr. Use the Claude Desktop integration below for normal use.

Claude Desktop integration

Locate your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the Salesmate server (see claude_desktop_config_example.json):
```
{
  "mcpServers": {
    "salesmate": {
      "command": "python",
      "args": ["C:\\absolute\\path\\to\\salesmate-mcp\\server.py"],
      "env": {
        "SALESMATE_API_KEY": "your-salesmate-access-token",
        "SALESMATE_BASE_URL": "https://yourcompany.salesmate.io"
      }
    }
  }
}
```
Notes:
- Use the absolute path to server.py.
- If you use a virtual environment, point command at that env's Python (e.g. C:\\path\\to\\salesmate-mcp\\.venv\\Scripts\\python.exe on Windows or /path/to/salesmate-mcp/.venv/bin/python on macOS/Linux).
- Credentials can be supplied either via the env block above or via a .env file next to server.py.
Restart Claude Desktop. The Salesmate tools will appear in the tool picker.

Usage examples (in Claude)

"Search Salesmate for contacts at Acme."
"Show me deals for contact 1024."
"Move deal 555 to the Negotiation stage."
"Create a task to follow up with contact 1024 due 2026-07-01."
"Add a note to contact 1024: spoke with procurement, decision by Q3."
"What are the recent activities for contact 1024?"

Configuration reference

Variable	Required	Default	Description
`SALESMATE_API_KEY`	✅	—	Salesmate Session Key (not the Access/Secret key).
`SALESMATE_BASE_URL`	✅	—	Workspace base URL (`https://...`).
`SALESMATE_AUTH_HEADER`		`accessToken`	Auth header name.
`SALESMATE_LINKNAME`		derived from `base_url`	Value for the required `x-linkname` header.
`SALESMATE_TIMEOUT`		`30`	Per-request timeout (seconds).
`SALESMATE_MAX_RETRIES`		`3`	Retry attempts for transient errors.
`SALESMATE_BACKOFF_FACTOR`		`0.5`	Base backoff delay (seconds).
`SALESMATE_LOG_LEVEL`		`INFO`	Logging verbosity.

Running the tests

pip install -e ".[dev]"
pytest

The suite uses pytest-asyncio and an in-memory httpx.MockTransport, so it runs fully offline and never touches the real Salesmate API.

Adapting to your Salesmate API version

Salesmate exposes several API versions and the exact endpoint paths and search payloads can differ between workspaces. All endpoint paths are centralised in salesmate/client.py in the ENDPOINTS dictionary, and the request bodies for search operations are small and self-contained — adjust them there if your workspace expects a different shape. The auth header name can be changed without code edits via SALESMATE_AUTH_HEADER.

License

MIT

Available Tools

8 tools

create_noteB

Create a note attached to a contact.

Args: contact_id: The numeric id of the contact to attach the note to. note: The note body text.

Returns: A structured object containing the created note.

ParametersJSON Schema

Name	Required	Description	Default
`note`	Yes
`contact_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It implies mutation but omits details on side effects, auth requirements, rate limits, or error handling. Minimal behavior disclosed beyond the obvious.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences plus structured Args/Returns. Very concise and front-loaded with action. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists so return value is hinted. Parameters are covered, but missing usage context, error scenarios, and constraints. Adequate for a simple tool but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description adds meaning by specifying contact_id as numeric and note as body text. This compensates but could be more detailed (e.g., constraints on note length).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it creates a note attached to a contact, distinguishing from sibling tools like create_task (different resource) and get_contact (read). However, it lacks explicit differentiation from other creation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use, when-not-to-use, or alternative tool guidance is provided. The description only states the tool's function without context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_taskA

Create a task in Salesmate.

Args: title: The task title. due_date: ISO-8601 due date (e.g. '2026-07-01' or '2026-07-01T09:00:00Z'). contact_id: Optional contact id to associate with the task.

Returns: A structured object containing the created task.

ParametersJSON Schema

Name	Required	Description	Default
`title`	Yes
`due_date`	Yes
`contact_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It only states creation and return of structured object, but no info on side effects, auth needs, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise, using a clear docstring format with bullet points. Every sentence adds value, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With output schema present, description doesn't need to detail return values. It covers all 3 parameters adequately. Missing broader context like potential side effects but sufficient for basic use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. It explains title, due_date (with ISO-8601 format example), and contact_id (optional). Adds meaningful context beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create a task in Salesmate' which is a specific verb and resource. It distinguishes from sibling 'create_note' by resource type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives (e.g., create_note). No mention of prerequisites or scenarios where it's inappropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_contactA

Retrieve a single contact's full details by its id.

Args: contact_id: The numeric id of the contact.

Returns: A structured object containing the contact record.

ParametersJSON Schema

Name	Required	Description	Default
`contact_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description clearly indicates a read-only retrieval operation, stating it returns full details without side effects. Somewhat lacking explicit read-only declaration, but adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact, front-loaded with the key action, and includes structured Args/Returns sections with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description sufficiently covers purpose, parameter, and return value for a simple get-by-id tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to the parameter 'contact_id' as numeric id, which the schema only defines as integer. Compensates for 0% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'Retrieve' and resource 'contact' with 'by its id', clearly differentiating from sister tools like search_contacts or list_deals.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when needing full details of a specific contact by ID, but provides no explicit guidance on when not to use or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_dealA

Retrieve a single deal's full details by its id.

Args: deal_id: The numeric id of the deal.

Returns: A structured object containing the deal record.

ParametersJSON Schema

Name	Required	Description	Default
`deal_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full behavioral burden. It indicates a read operation ('retrieve') but does not disclose behaviors such as error handling (e.g., 404 if not found), idempotency, authentication requirements, or rate limits. Minimal behavioral context is provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—only 5 lines—with a clear front-loaded purpose statement followed by parameter and return documentation. Every sentence serves a purpose without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and has an output schema, so return value details are covered by schema. However, it lacks information on edge cases (e.g., missing deal), response error handling, and usage in conjunction with siblings. For a basic get tool, it meets minimum viability but could be more comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, deal_id, is described in an Args section as 'The numeric id of the deal.' While the schema already specifies integer type, the description adds clarity about its role and that it is numeric. Given 0% schema description coverage, the description fully documents the parameter's meaning, adding value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('retrieve'), the resource ('deal'), and the scope ('single', 'full details'). It effectively distinguishes from siblings like list_deals (multiple deals) and search_contacts (different resource).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use when needing full details of a single deal, but lacks explicit guidance on when not to use it (e.g., for multiple deals, use list_deals) or alternatives among siblings. No exclusion or prerequisite information is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_recent_activitiesB

Get recent activities (calls, meetings, emails) for a contact.

Args: contact_id: The numeric id of the contact.

Returns: A structured object with the contact's recent activities.

ParametersJSON Schema

Name	Required	Description	Default
`contact_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description states it's a read operation returning a structured object, but with no annotations, it doesn't disclose traits like read-only safety, error handling, or side effects. It provides basic transparency but lacks depth expected for a tool without annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with no wasted words, front-loading the purpose and directly stating the argument and return value. Every sentence is essential.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, output schema exists), the description covers the basics. However, it omits potential context like result limits or ordering, leaving some gaps for a complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description adds meaning by clarifying contact_id is the numeric id, beyond the schema's type and title. However, it's minimal and obvious, so it only reaches baseline adequacy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves recent activities (calls, meetings, emails) for a contact, using a specific verb and resource. It distinguishes from sibling tools like get_contact or get_deal by focusing on activities, though it doesn't explicitly contrast with alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description implies usage when you need recent activities for a contact, but offers no exclusions or context for when not to use it, making it minimally helpful for an AI agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_dealsA

List deals, optionally filtered to a specific contact.

Args: contact_id: Optional contact id to filter deals by.

Returns: A structured object with the matching deals.

ParametersJSON Schema

Name	Required	Description	Default
`contact_id`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry behavioral context. It states the tool returns a structured object, implying read-only access, but does not explicitly confirm no side effects, no disclosure of pagination or rate limits. Adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences plus structured args/returns), front-loaded with purpose, and every part serves a function without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with one optional parameter and an output schema, the description covers the essential aspects. However, it omits details like ordering, pagination, or error handling, which lowers completeness slightly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains the single optional parameter 'contact_id' as a filter, which adds meaning beyond the schema's type and nullability. With schema coverage at 0%, the description compensates well for the undocumented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists deals with an optional filter by contact. The verb 'list' and resource 'deals' are unambiguous. It distinguishes from sibling 'get_deal' (single deal) and 'search_contacts' (contacts) implicitly, but could be more explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lacks explicit guidance on when to use this tool versus alternatives like 'get_deal' for a single deal or 'search_contacts'. The parameter explanation is provided, but no 'when to use' or 'when not to use' context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_contactsB

Search for contacts in Salesmate by name, email, or company.

Args: query: Free-text search term.

Returns: A structured object with the matching contacts.

ParametersJSON Schema

Name	Required	Description	Default
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behaviors. It only states it returns a structured object, without mentioning pagination, rate limits, or what happens with no matches. The mutation is not destructive, but details are minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a clear main sentence followed by Args and Returns sections. It is front-loaded and every sentence serves a purpose, though the Returns section could be more specific.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only one parameter and no annotations, the description covers the essential information. The presence of an output schema reduces the need to describe return values in detail. However, search behavior (e.g., exact vs. partial matching) is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description adds value by describing the 'query' parameter as 'Free-text search term.' This goes beyond the schema's type/title but does not explain nuances like case sensitivity or wildcards.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches for contacts by name, email, or company. It specifies the resource (contacts) and action (search), distinguishing it from sibling tools like get_contact (exact lookup) or list_deals (different resource).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., when to use get_contact for exact ID lookups). The description implies free-text search but does not explicitly state context or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_deal_stageA

Move a deal to a new pipeline stage.

Args: deal_id: The numeric id of the deal to update. stage: The name of the target stage.

Returns: A structured object containing the updated deal record.

ParametersJSON Schema

Name	Required	Description	Default
`stage`	Yes
`deal_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states the action and return, omitting side effects, authorization requirements, or error handling. Agents lack information on whether the operation is reversible or idempotent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: one sentence for purpose, followed by compact arg/return documentation. Every sentence earns its place with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool, the description covers the core action and return. However, it omits validation details (e.g., stage must exist), potential errors, and concurrency concerns, leaving minor gaps for a fully informed agent decision.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, but the description adds clarity by specifying deal_id as 'numeric id' and stage as 'name of target stage'. This compensates for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'move' and clearly identifies the resource 'deal' and object 'pipeline stage'. It effectively distinguishes from sibling tools like create_note and list_deals.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives, such as when to update other deal fields. The description is purely functional without any contextual when/when-not or alternative recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

8 tool updatesv1.0.0Jul 12, 2026
- First observedcreate_note
- First observedcreate_task
- First observedget_contact
- First observedget_deal
- First observedget_recent_activities
- First observedlist_deals
- First observedsearch_contacts
- First observedupdate_deal_stage

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-07-12 05:50 across 8 tools

Disambiguation5/5

Each tool targets a distinct operation (create note, create task, get contact, get deal, get activities, list deals, search contacts, update deal stage) with no overlap.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (e.g., create_note, get_contact, update_deal_stage), making it predictable.

Tool Count5/5

8 tools is well within the 3-15 range, covering core CRM entities (contacts, deals, tasks, notes) without being excessive.

Completeness2/5

Missing fundamental CRUD operations: no create or update for contacts, no create deal, no delete functionality. Users cannot create new contacts or deals, only attach notes/tasks to existing ones.

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Artificial Wit AIOAuth
com.artificialwit
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
ERP Systems CRM Knowledge & Memory
2
Relm CRM A
com.relmcrm
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
CRM AI & Machine Learning
412
LeadFoxConnectOAuth
io.github.LeadFox-Shay
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Marketing CRM
2
agentcentral AOAuth
to.agentcentral
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
E-commerce & Retail Customer Support
26

Related MCP Servers

Salesforce MCP Server
Customer Data Platforms Databases
usama-dtc
A
license
A
quality
D
maintenance
An MCP server implementation that integrates Claude with Salesforce, enabling natural language interactions with Salesforce data and metadata.
Updated a year ago (2025-03-24 21:20 UTC)
8
52 npm
MIT
MCP-Server
File Systems Browser Automation Developer Tools
prajna-gajendra-acharya
A
license
Not graded
quality
D
maintenance
A production-ready MCP server with file management, HTTP requests, system info, and environment variable tools, plus a management UI and dual transport for Claude Desktop and Claude.ai.
Updated 5 months ago (2026-04-08 02:24 UTC)
205 npm
MIT
pipedrive-mcp
CRM Search
Dimkanarb-afk
A
license
Not graded
quality
D
maintenance
Full-featured Pipedrive MCP server for Claude Desktop, enabling natural language control over deals, leads, persons, organizations, notes, activities, pipelines, and more via 34 tools and 7 prompts.
Updated 6 months ago (2026-03-17 21:41 UTC)
7 npm
MIT
Follow Up Boss Connector
CRM App Automation
thehillisrockin
F
license
Not graded
quality
C
maintenance
A self-hosted MCP server that connects a Follow Up Boss CRM account to Claude, enabling CRM operations through natural language via 25 curated tools and a raw API tool.
Updated 2 months ago (2026-07-22 05:59 UTC)
-

Salesmate MCP Server

Get started

Option A - One-click install (.mcpb, no terminal)

Build the bundle yourself

Option B - Clone & connect (manual)

You must provide your own secrets

Features

Tools

Project structure

Installation

1. Prerequisites

2. Get the code

3. Create and activate a virtual environment

4. Install dependencies

5. Configure environment variables

6. Run the server

Claude Desktop integration

Usage examples (in Claude)

Configuration reference

Running the tests

Adapting to your Salesmate API version

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Resources

Related MCP Connectors

Related MCP Servers

Option A - One-click install (`.mcpb`, no terminal)