From Read-Only to Responsible Action: Rebuilding the Pipedrive CRM MCP Server for 2.x

When I first open-sourced the Pipedrive CRM MCP Server, the objective was straightforward: let an AI assistant search and analyze CRM data without giving it permission to change anything.

Version 1.x proved that the concept worked. An assistant could retrieve deals, contacts, organizations, pipelines, notes, and custom fields through the Model Context Protocol.

But a useful prototype and a dependable operational tool are not the same thing.

The work behind Pipedrive CRM MCP Server 2.x has been about closing that gap. Version 2.0 rebuilds the read-only foundation. The work planned for 2.1 introduces a carefully constrained way to take action—without abandoning safe defaults.

The Biggest Change Is Under the Surface

The most important part of 2.0 is not a new prompt or another CRM query. It is the architecture.

The original implementation concentrated most of the server in one large file. That made the project easy to start, but harder to test, reason about, and secure as its capabilities grew.

Version 2.0 separates the system into clear responsibilities:

• Configuration and startup validation
• Pipedrive CRM API access
• MCP tool registration
• Local and remote transports
• Session management
• Server lifecycle and shutdown

That separation matters because an AI integration is not simply an API wrapper. It is a control point between a model and an operational system.

Each part needs to be testable independently, and the boundaries need to remain understandable as the project evolves.

A More Predictable Contract With Pipedrive CRM

Version 2.x now uses Pipedrive CRM API v2 for deals, people, organizations, pipelines, stages, leads, and general item search.

Pipedrive CRM has not moved every resource to v2, so users and notes remain behind isolated v1 adapters. That distinction is explicit rather than hidden inside the rest of the integration.

The tool responses have also been standardized.

List and search operations return a predictable structure containing the records, record count, pagination cursor, applied filters, and an indication when a result was truncated. Single-record requests use a consistent item response.

Errors are sanitized before they reach the AI client. Raw API responses, credentials, and token-bearing URLs are not exposed.

This gives the model a more reliable contract and gives operators a clearer understanding of what information can leave the integration boundary.

Version 2.0 also removes two hidden behaviors from the original deal query. A request no longer silently limits results to open deals or deals with activity in the previous 365 days.

Defaults should help the user—not quietly change the meaning of the question.

Modern Remote Access With Safer Defaults

Local MCP clients can continue to launch the server using standard input and output.

For remote clients, version 2.0 adds modern Streamable HTTP support at the /mcp endpoint. The older SSE routes remain available as a compatibility layer during 2.x, but they are deprecated and planned for removal in 3.0.

Remote access is also where configuration mistakes become security problems, so 2.0 is intentionally opinionated.

The server binds to the local machine by default. Binding it to a non-local address requires both a sufficiently long JWT secret and an explicit hostname allowlist.

The server also supports:

• Exact CORS origin allowlists rather than wildcard access
• Host-header validation
• Independent MCP server instances for each HTTP session
• Configurable session limits and idle timeouts
• Clean session shutdown
• Rate limiting for Pipedrive CRM requests
• A health endpoint that reveals service status without exposing configuration

The built-in server does not pretend to replace a production edge. Remote deployments should still sit behind a trusted HTTPS reverse proxy, with the application port kept private.

Security improves when the software makes the safe deployment path obvious.

Version 2.0 Remains Strictly Read-Only

The v2.0.0 release does not create, update, or delete Pipedrive CRM records.

That was a deliberate decision.

Before allowing an AI system to change CRM data, I wanted a stable foundation: predictable responses, proper pagination, isolated sessions, modern transport support, sanitized errors, startup validation, automated tests, and a controlled release process.

Read-only access is useful on its own. It allows an assistant to answer questions such as:

• Which deals are currently in each pipeline stage?
• What are the highest-value visible opportunities?
• Which contacts are associated with a specific organization?
• What notes and custom fields are attached to a deal?
• How do two sales pipelines compare?

The AI can retrieve and analyze the information, but the human remains responsible for changing the system of record.

The Next Step: Gated, Preview-First Writes

The next stage of the 2.x work explores a narrow path from analysis to action.

The proposed 2.1 implementation does not enable broad CRM access. It introduces only two write tools:

• Move a deal to another stage
• Add a plain-text note to a deal

More importantly, neither tool is available by default.

An operator must explicitly name each permitted tool in the server configuration. If the write-tool allowlist is empty, the server remains read-only and the AI client cannot even discover the write tools.

Enabling a tool still does not make every call execute automatically. Both tools operate in preview mode unless the request includes an explicit execute: true.

That creates three distinct gates:

1. The server operator enables a specific write capability.
2. The assistant prepares and previews the proposed operation.
3. Execution must be requested explicitly.

This is a much stronger model than exposing generic create, update, and delete operations and relying only on the model to use them carefully.

Guardrails Need to Reflect the Operation

Different write operations carry different risks, so each tool has its own controls.

Moving a deal requires the caller to provide the stage it expects the deal to be in. Immediately before updating the record, the server retrieves the current deal and compares the stages.

If another user or system has already moved the deal, the request is rejected as stale.

This is a best-effort optimistic check rather than a perfect transaction. Pipedrive CRM does not provide an atomic conditional stage update, so another client could still make a change between the check and the update. That limitation is documented rather than hidden.

Adding a note creates a different risk. Notes are not idempotent: repeating the same request can create a duplicate. If the result of a request is ambiguous, the server tells the client to verify the deal before trying again.

Note content is treated as plain text, limited in length, and HTML-escaped before being sent to Pipedrive CRM.

Write operations also produce metadata-only audit events recording the operation, entity ID, outcome, and timestamp. Note contents and credentials are deliberately excluded.

There are still no delete tools, no broad CRUD interface, and no default write access.

A Progressive Model for Trust

The pattern behind these changes is larger than Pipedrive CRM:

1. Observe the system.
2. Produce a proposed action.
3. Let an operator enable only the actions they accept.
4. Preview before execution.
5. Validate the current state.
6. Record the outcome without logging sensitive content.

Companies do not need to choose between AI that can only answer questions and AI with unrestricted authority.

There is a useful middle ground: narrowly scoped actions with explicit configuration, meaningful previews, operational guardrails, and honest documentation of the remaining risks.

That is the direction of Pipedrive CRM MCP Server 2.x.

Getting Started

Version 2.0 requires Node.js 22 or 24 and a Pipedrive CRM API token. It supports local MCP clients, Streamable HTTP, Docker, and published container images.

Anyone upgrading from 1.x should review the migration instructions in the repository. The transport configuration, pagination model, response contract, and several environment variables have changed.

The gated-write implementation is being developed separately for 2.1 and should be treated as upcoming work until it has completed its sandbox, security, and release gates.

The project remains open source under the MIT License. Issues, testing feedback, and contributions are welcome on GitHub.

The future of enterprise AI is not simply giving models more access. It is giving them the right access, through boundaries we can understand and control.

That is what I want 2.x to demonstrate.