Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Pipedrive MCP Server show me my recent deals that are overdue"
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.
A single-tenant, self-hosted Model Context Protocol server for Pipedrive. Version 2.x uses Pipedrive API v2 for deals, persons, organizations, pipelines, stages, leads, and item search. Notes and users remain isolated behind clearly scoped v1 adapters because Pipedrive has not moved those APIs to v2.
The server is read-only by default. Two narrowly scoped write tools can be enabled explicitly and remain preview-first.
Node.js 22 or 24 (Node 24 recommended)
A Pipedrive API token
PIPEDRIVE_DOMAIN is not used. The official Pipedrive client supplies the API base URL.
Related MCP server: Pipedrive MCP Server
Install globally:
npm install --global pipedrive-mcp-server
PIPEDRIVE_API_TOKEN=your-token pipedrive-mcp-serverOr build this repository:
npm ci
npm run check
PIPEDRIVE_API_TOKEN=your-token npm startExample desktop MCP configuration:
{
"mcpServers": {
"pipedrive": {
"command": "pipedrive-mcp-server",
"env": {
"PIPEDRIVE_API_TOKEN": "your-token"
}
}
}
}The modern HTTP endpoint defaults to http://127.0.0.1:3000/mcp:
PIPEDRIVE_API_TOKEN=your-token \
MCP_TRANSPORT=http \
pipedrive-mcp-serverGET /health is unauthenticated, host-validated, and returns only service status. The server creates an independent MCP server and transport for every session and closes active sessions during shutdown.
Binding to a non-loopback address requires both an HS256 JWT secret of at least 32 characters and an explicit hostname allowlist:
PIPEDRIVE_API_TOKEN=your-token \
MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_ALLOWED_HOSTS=mcp.example.com \
MCP_ALLOWED_ORIGINS=https://app.example.com \
MCP_JWT_SECRET='replace-with-at-least-32-random-characters' \
pipedrive-mcp-serverThe built-in HTTP server does not terminate TLS. Never expose it directly on an untrusted network: place it behind a trusted HTTPS reverse proxy, keep the application port private, and configure the proxy to replace (not append to) forwarding headers. JWT bearer tokens are replayable if captured. Docker Compose therefore publishes the service only on host loopback by default; remote operators must add a TLS terminator before changing that binding.
Clients send Authorization: Bearer <token>. Tokens must use HS256. MCP_JWT_ISSUER and MCP_JWT_AUDIENCE add optional claim validation. There is no boot-token setting.
MCP_ALLOWED_ORIGINS is an exact, comma-separated allowlist. When it is empty the server emits no CORS headers; wildcard CORS is not supported. MCP_ALLOWED_HOSTS contains hostnames only, without schemes, paths, or ports.
The deprecated compatibility routes are GET /sse and POST /messages. They are enabled by default in 2.x and can be disabled with MCP_ENABLE_LEGACY_SSE=false. MCP_TRANSPORT=sse remains an alias for HTTP mode and emits a warning. These routes are planned for removal in 3.0.
Copy .env.example to .env, set PIPEDRIVE_API_TOKEN, and set a random MCP_JWT_SECRET of at least 32 characters. Then run:
docker compose up --build -d
docker compose psCompose serves /mcp on port 3000, requires JWT for MCP routes, runs as the unprivileged node user, and checks /health with Node’s built-in fetch. Published images use ghcr.io/willdent/pipedrive-mcp-server.
For stdio in Docker, override the transport and disable the HTTP health check:
docker run --rm -i --no-healthcheck \
-e PIPEDRIVE_API_TOKEN=your-token \
-e MCP_TRANSPORT=stdio \
ghcr.io/willdent/pipedrive-mcp-server:latestRead tools:
get-users
get-deals, get-deal, get-deal-notes, search-deals
get-persons, get-person, search-persons
get-organizations, get-organization, search-organizations
get-pipelines, get-pipeline, get-stages
search-leads, search-all
List/search tools return JSON text and structured content shaped as:
{
"items": [],
"count": 0,
"nextCursor": "optional-cursor",
"truncated": false,
"filters": {}
}Single-record tools return { "item": {} }. Stable failures return { "code", "message", "retryable" } with MCP isError: true; raw API errors, credentials, and token-bearing URLs are not exposed.
get-deals has no hidden status or activity-date defaults. It supports owner, stage, pipeline, status, updated-time, value, cursor, limit, and generic custom-field selection. Page size defaults to 100 and is capped at 500. Value filtering scans at most 2,000 deals and reports truncated and nextCursor when more records remain. Use search-deals for title searches.
No write tools are registered unless named in PIPEDRIVE_WRITE_TOOLS:
PIPEDRIVE_WRITE_TOOLS=move-deal,add-deal-notemove-deal requires dealId, targetStageId, and expectedCurrentStageId. It performs a best-effort optimistic stale-state check immediately before the update. Pipedrive does not expose an atomic conditional stage update, so concurrent changes by another client can still race this check.
add-deal-note accepts at most 10,000 characters of plain text and HTML-escapes it before sending.
Both tools preview by default. A mutation happens only with execute: true.
Audit output contains only operation, entity ID, outcome, and timestamp—never note contents or credentials.
Variable | Default | Purpose |
| required | Pipedrive API token |
|
|
|
|
| HTTP bind address |
|
| HTTP port |
|
| Streamable HTTP path |
| local hosts | Exact hostname allowlist |
| empty | Exact CORS origin allowlist |
|
| Keep |
|
| Maximum combined HTTP/SSE sessions |
|
| Close sessions idle longer than this duration |
| empty | HS256 secret; required off loopback |
| empty | Optional JWT issuer |
| empty | Optional JWT audience |
| empty | Explicit write-tool allowlist |
|
| Minimum delay between queued calls |
|
| Maximum concurrent calls |
All ports, paths, numeric limits, origins, hosts, boolean values, and tool names are validated at startup.
Upgrade Node to 22 or 24.
Remove PIPEDRIVE_DOMAIN, MCP_JWT_TOKEN, MCP_JWT_ALGORITHM, and MCP_ENDPOINT.
Replace HTTP MCP_TRANSPORT=sse with MCP_TRANSPORT=http; keep the alias temporarily if a client still uses legacy SSE.
Point modern clients at /mcp; legacy clients may use /sse through 2.x.
Update callers for cursor pagination and the structured response contract.
Review deal queries: get-deals no longer silently forces open status or a 365-day activity window.
Leave PIPEDRIVE_WRITE_TOOLS empty until each write has been reviewed and sandbox-tested.
npm run typecheck
npm test
npm run build
npm run validate:packageSee docs/release-checklist.md for automated, Docker, and manual Pipedrive sandbox gates. Releases are tag-driven and use npm trusted publishing plus GHCR semantic tags.
Version 2.x remains single-tenant and self-hosted. Pipedrive OAuth, MCP OAuth, persistent sessions, broad CRUD, and destructive delete tools are intentionally out of scope.
MIT
Get a Pipedrive deal by ID, including generic custom fields.
| Name | Required | Description | Default |
|---|---|---|---|
| dealId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, which covers safety traits. The description adds extra context by noting that custom fields are included in the response, which is beyond what annotations provide. This helps the agent understand the richness of the returned data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff. It efficiently communicates the core purpose and a key feature (custom fields). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with one parameter and no output schema, the description is largely complete. It states the action, resource, and a notable aspect (custom fields). It does not describe the response format, but given the lack of output schema and the tool's simplicity, this is acceptable. A brief note on what the deal object contains would push it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter (dealId) with no description (0% coverage). The description's phrase 'by ID' clarifies the parameter's role, and the parameter name is self-explanatory. While the description does not explicitly restate the parameter details, the tool's simplicity makes this sufficient. However, it could be improved by confirming the expected integer format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Get) and the resource (a Pipedrive deal by ID), and specifies that it includes generic custom fields. This distinguishes it from sibling tools like 'get-deals' (plural) which likely lists deals, and 'search-deals' which searches. The verb+resource+scope is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific deal ID, but it does not explicitly state when to use this tool over alternatives like 'get-deals' or 'search-deals'. There are no exclusions or conditional guidance, which is a gap for an AI agent choosing among similar tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List notes attached to a Pipedrive deal.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| dealId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, making this a safe read operation. Description adds minimal context beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Six-word sentence with zero waste; appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite rich annotations, the description lacks details about pagination (cursor, limit) and output format, which is not covered by an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, requiring the description to compensate. However, the description provides no information about parameters (limit, cursor, dealId) beyond the schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses explicit verb 'List' and resource 'notes attached to a Pipedrive deal', clearly distinguishing it from sibling tools like get-deal which return deals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 like search-deals or get-deal; no exclusions or prerequisites given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List visible, non-archived Pipedrive deals without hidden status or date defaults.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| status | No | ||
| ownerId | No | ||
| stageId | No | ||
| maxValue | No | ||
| minValue | No | ||
| scanLimit | No | ||
| pipelineId | No | ||
| updatedSince | No | ||
| updatedUntil | No | ||
| customFieldKeys | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that deals are visible and non-archived without hidden status or date defaults, which provides some behavioral context but does not significantly extend beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It efficiently conveys the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters, no output schema, and no parameter documentation, the description is insufficient. It omits details about pagination, filtering semantics, and result expectations, which are critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 12 parameters (e.g., limit, cursor, status, ownerId). The description adds no meaning to the input schema, leaving the agent to infer parameter purposes from names and constraints alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists visible, non-archived Pipedrive deals, which distinguishes it from sibling tools like 'get-deal' (single deal) or 'search-deals' (search with complex queries). The verb 'list' and resource 'deals' are explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus siblings like 'search-deals' or 'get-deal'. No context about prerequisites, applicable scenarios, or alternatives is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Pipedrive organization by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| organizationId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description merely restates 'get' without adding any behavioral details beyond annotations, such as potential error conditions or response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise and front-loaded. However, it lacks structure (e.g., bullet points) and could include more information without becoming verbose. It is minimally acceptable but not exemplary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and multiple sibling tools, the description should specify what is returned (e.g., full organization object) and how it differs from get-organizations. Currently, it omits these details, making it incomplete for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to clarify the meaning of organizationId beyond the schema's exclusiveMinimum:0. It does not mention that the ID must correspond to an existing organization or explain what happens for invalid IDs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), resource ('Pipedrive organization'), and method ('by ID'). It effectively distinguishes from sibling tools like get-organizations (plural listing) and search-organizations (search) by specifying retrieval of a single organization via its ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives such as get-organizations for listing all organizations or search-organizations for filtering. There is no mention of prerequisites or context like requiring an existing organization ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Pipedrive organizations.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds no behavioral details beyond 'list', such as pagination behavior, rate limits, or scope of results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence effectively communicates the core purpose, with no extraneous text. However, it may be overly minimal for a tool with pagination parameters; slightly more detail would improve usability without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no parameter documentation, and no usage guidance, the description fails to provide sufficient context for correct usage. A list tool with pagination params should explain cursor-based pagination and result format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (limit, cursor) with 0% schema description coverage. The description provides no explanation of these parameters, their roles in pagination, or acceptable values beyond what the schema's type constraints indicate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'Pipedrive organizations', establishing a specific retrieve action. However, it does not differentiate from sibling tools like 'get-organization' (single entity) or 'search-organizations', which is acceptable given the distinct verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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. Siblings include 'get-organization' for individual retrieval and 'search-organizations' for filtered queries, but the description provides no context for choosing among them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Pipedrive person by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| personId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds minimal behavioral context beyond 'Get by ID'. No mention of response format or error cases, but with annotations covering safety, this is acceptable but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information, no filler. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, rich annotations), the description is sufficiently complete for a basic retrieval operation. Missing error handling details but not critical for this use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (personId) with 0% schema description coverage. Description implies the parameter is the ID, which aligns with schema. However, it does not provide additional details like format, source, or validation beyond the schema. Adequate for a simple integer parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (Get), resource (Pipedrive person), and identifier method (by ID). This distinguishes it from siblings like get-persons (list all) and search-persons (search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this vs alternatives like get-persons or search-persons. The description does not provide use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Pipedrive persons.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint: true, openWorldHint: true, idempotentHint: true, and destructiveHint: false, which the description does not contradict. However, the description adds no behavioral context beyond these annotations, such as whether pagination is supported, rate limits, or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is excessively short (4 words) and lacks useful detail. Brevity is not conciseness here, as critical information is omitted. A better structure would front-load the core purpose and follow with parameter guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, zero parameter documentation, and numerous sibling tools, the description is severely incomplete. It fails to clarify return format, pagination behavior, or distinguish from similar list/search tools, leaving the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about the 'limit' and 'cursor' parameters. The agent must infer their meaning solely from the schema, which is insufficient for correct parameter value construction.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Pipedrive persons' uses a clear verb ('List') and resource ('Pipedrive persons'), making the purpose immediately understandable. However, it does not distinguish this tool from the sibling 'search-persons' which also lists persons, lacking specificity on filtering or scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 like 'search-persons' or 'get-person'. There is no mention of use cases, prerequisites, or exclusions, leaving the agent 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.
Get a Pipedrive pipeline by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| pipelineId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint=false, indicating safe, idempotent read. The description adds no further behavioral context (e.g., error handling, null returns). Adequate but not enhanced beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundant words, front-loaded with action and resource. Efficient but could include minor additional context without significant bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low schema coverage and no output schema, the description lacks essential context about return values, domain knowledge (what is a 'pipeline'?), and how to interpret results. Incomplete for effective agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description offers no details about the single parameter 'pipelineId' beyond 'by ID'. It fails to clarify the integer type, required constraint, or exclusiveMinimum, requiring the agent to infer from schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'Pipedrive pipeline', specifying identification 'by ID'. It is specific and distinct from sibling tools like 'get-pipelines' which retrieves multiple pipelines.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 such as 'get-pipelines' (plural) or other sibling tools. Lacks context about prerequisites or expected use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Pipedrive pipelines.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations fully cover safety (readOnlyHint, idempotentHint), but the description adds no behavioral traits beyond 'list'. It does not mention pagination behavior (cursor, limit) or that results are incremental, even though these are implied by parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence), but this brevity sacrifices necessary detail about parameters and usage. It is front-loaded but underspecified for a tool with two parameters and no output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and limited description, the tool definition fails to convey response format or practical invocation details (e.g., how to paginate). Complexities like cursor management are not addressed, making it incomplete for agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the tool description provides no explanation for the 'limit' and 'cursor' parameters. The agent must infer their meaning from constraints alone, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Pipedrive pipelines' clearly states the action (list) and resource (pipelines), distinguishing it from siblings like get-pipeline (singular). However, it lacks specificity about scope (e.g., which pipelines, filtering) compared to high-quality examples.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 such as get-pipeline for a single pipeline or search-pipelines (if exists). The description does not mention prerequisites or context, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Pipedrive stages, optionally filtered by pipeline.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| cursor | No | ||
| pipelineId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description adds little beyond stating the operation is a list. It does not mention pagination behavior or auth requirements, but the annotations cover the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. However, it is too brief given that the schema lacks parameter descriptions, so it does not adequately inform the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite annotations providing safety context, the description lacks information about the return structure, pagination behavior, and parameter details. For a tool with no output schema and 0% schema description coverage, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the input schema provides no field descriptions. The tool description does not explain any of the three parameters (limit, cursor, pipelineId), leaving the agent with only the parameter names and types. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List Pipedrive stages, optionally filtered by pipeline.' It uses a specific verb and resource, and the mention of filtering distinguishes it from sibling tools like get-pipelines or get-deals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates an optional filter but provides no explicit guidance on when to use this tool versus alternatives, nor any conditions or exclusions. It is adequate for a simple list operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Pipedrive users/owners.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, idempotentHint=true. The description adds no behavioral details beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary information, perfectly sized for its purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with no parameters, good annotations, and no output schema, the description is complete enough to inform the agent of what the tool does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and the description does not need to add parameter info. According to guidelines, 0 parameters yields baseline 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List Pipedrive users/owners.' clearly specifies the verb 'list' and the resource 'users/owners', which is unique among sibling tools that focus on deals, persons, organizations, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 vs alternatives. There are no sibling user tools, so it's implied to be the only option, but no context is added.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across supported Pipedrive item types.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | ||
| limit | No | ||
| cursor | No | ||
| itemTypes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint as false, covering the safety profile. The description adds minimal behavioral context beyond stating it is a search across types, missing details like pagination or that results may be partial (open world).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise and front-loaded. However, for a tool with 4 parameters and no schema descriptions, it may be too brief, sacrificing essential information. No wasted words, but completeness is lacking.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 params, 0% schema coverage, no output schema), the description is incomplete. It fails to explain how parameters work, pagination via cursor, the range of item types, or what the response contains. The annotations cover safety, but the description omits critical usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain the purpose and constraints of the 4 parameters. However, it provides no parameter details. The meaning of 'term', 'limit', 'cursor', and 'itemTypes' must be inferred from names and schema types, and the enum for 'itemTypes' is ambiguous (single string vs. multiple).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search across supported Pipedrive item types' clearly states the tool's function: it searches multiple item types. The verb 'search' and the resource 'supported Pipedrive item types' are specific, and the tool is distinguished from siblings like 'search-deals' which target a single type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'search-deals' or 'search-persons' is provided. The name 'search-all' implies cross-type usage, but the description does not state when not to use it or mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Pipedrive deals by title, notes, or searchable custom fields.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | ||
| limit | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only nature is conveyed. Description adds that it searches by title, notes, or custom fields, but lacks details on pagination or exact matching behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no redundancy. Every word adds value given the context of a search tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 3 parameters and no output schema, the description is brief. It lacks explanation of result format, pagination, and search behavior (e.g., partial match, case sensitivity), leaving gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; description does not explain the 'term', 'limit', or 'cursor' parameters beyond what the schema provides. Agent may not understand what 'term' accepts or how pagination works.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Search Pipedrive deals by title, notes, or searchable custom fields.' It specifies the resource (deals) and the searchable fields, effectively differentiating from sibling tools like get-deals or search-persons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for textual search but does not explicitly compare with siblings like get-deals (which might list or filter) or search-all. No 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.
Search Pipedrive leads.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | ||
| limit | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnly, idempotent, non-destructive) already cover the safety profile. The description adds no additional behavioral context such as pagination behavior, rate limits, or result format, which would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three words, which is concise but under-specified. It does not earn its space by adding value beyond the tool name. For a tool with three parameters and no schema descriptions, more detail is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and schema descriptions, the description is severely inadequate. It fails to explain search behavior, pagination, or what constitutes a 'lead,' leaving the agent with insufficient context to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description itself does not explain any parameters. The agent must infer meaning from parameter names alone (term, limit, cursor), which is insufficient for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search Pipedrive leads' states the action and resource clearly, but it lacks differentiation from sibling tools like search-persons or search-deals. The term 'leads' may be ambiguous without clarifying its distinct role in Pipedrive.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not specify when to use this tool over alternatives or mention any prerequisites, making it difficult for an agent to select correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Pipedrive organizations.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | ||
| limit | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false, so the tool's safety profile is clear. The description adds no additional behavioral context (e.g., pagination behavior), but given the annotations, the lack is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (3 words) but omits critical details about parameters and behavior. This is under-specification, not effective conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and no output schema, the description lacks essential information about pagination, parameter constraints, and return format. It is insufficient for an agent to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain each parameter (term, limit, cursor). Instead, it provides no parameter information, leaving the agent without guidance on how to construct valid inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Search Pipedrive organizations' clearly identifies the action (search) and the resource (organizations). This distinguishes it from sibling tools like search-deals or search-persons, which target different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get-organizations, get-organization, or search-all. There is no mention of preferred use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Pipedrive persons.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | ||
| limit | No | ||
| cursor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety (read-only, non-destructive, idempotent, open-world). The description adds no behavioral context beyond those annotations, such as pagination behavior or query limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
At two words, the description is too short to be informative. It lacks structure and does not earn its place; essential information is missing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite rich annotations, the description omits key details such as required parameter semantics (term), pagination (cursor), and output format. The tool is inadequately documented for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameter (term, limit, cursor). The agent must infer meaning from parameter names alone, which is insufficient for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Search Pipedrive persons.' It clearly identifies the action (search) and resource (persons). This distinguishes it from sibling tools like 'get-person' (single fetch) and 'get-persons' (likely list all), but provides no additional detail about the type of search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 such as 'get-persons' or 'search-deals'. The agent receives no help in deciding which search to invoke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v2.1.0get-dealget-deal-notesget-dealsget-organizationget-organizationsget-personget-personsget-pipelineget-pipelinesget-stagesget-userssearch-allsearch-dealssearch-leadssearch-organizationssearch-personsEach tool targets a distinct entity or operation (e.g., get-deals vs. get-deal vs. search-deals). The differences are clear from descriptions, reducing ambiguity.
All tools use a consistent verb_noun pattern (e.g., get-users, search-persons). List operations use plural nouns, single retrieval uses singular, and searches are prefixed with 'search-'.
With 16 tools, the count is slightly above the typical 3-15 range but still reasonable for covering multiple CRM entities. No tools are redundant.
Only read operations are provided (list, get, search). Missing create, update, delete tools, which are essential for a CRM server. Agents cannot perform any write actions.
Read deals, persons, organizations, activities and pipelines; create and update CRM records.
The HubSpot MCP Server acts as a bridge that enables AI assistants and Large Language Models to securely interact with HubSpot CRM data through natural conversation, without requiring users to understand complex API structures. It provides read-only access to standard CRM objects (contacts, companies, deals, tickets, products, invoices, and more) and their associations, secured via OAuth 2.0, allowing AI agents to perform tasks like summarizing deals, fetching company updates, and looking up record changes.
Operate the Plixana CRM from any AI: contacts, deals, quotes, WhatsApp and metrics.
Read-only AI access to HAVN properties, leads, tasks, files, media, and analytics.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/WillDent/pipedrive-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
