How to connect a Pipedrive MCP with Codex (4 steps)

When you hand Codex a task to build a Pipedrive sync or a deal-reporting feature, you usually describe the data in the prompt.

That description can be incomplete in a way that matters more for Pipedrive than most tools. Custom field keys are random hash strings, not readable names, and pipeline and stage IDs are account-specific integers.

So Codex writes a parser keyed to a field that doesn't exist, a stage-transition check against the wrong ID, or a type definition that omits half the custom fields your account actually uses.

To give Codex direct access to Pipedrive as it works through your coding tasks, we'll show you how to connect Pipedrive with Merge Agent Handler's Pipedrive MCP server.

How it works

Merge Agent Handler connects Codex to the Pipedrive API through the Merge CLI. You install the CLI, authenticate once, and run a single setup command from your project root.

That command writes a Merge CLI section to your project's AGENTS.md file, which tells Codex when to call merge search-tools and merge execute-tool to reach Pipedrive.

Once connected, Merge handles API token storage and refresh on your behalf, so you never put a Pipedrive token in your repo or manage its rotation yourself.

Related: How to use the Pipedrive MCP in Claude Code

Prerequisites

Before getting started, you'll need the following:

• A Merge Agent Handler account
• Codex access (available via the OpenAI platform)
• pipx installed (run pipx --version to confirm, or install via pip install pipx)
• A Pipedrive account with API access to the company data your tasks need

If you want to connect Merge Agent Handler's Pipedrive MCP with internal or customer-facing agentic products, you can follow the steps in our docs.

1. Install the Merge CLI

Install the Merge CLI with pipx: pipx install merge-api

Verify the install: merge --version

2. Log in to Merge

Run the following to authenticate the CLI with your Merge Agent Handler account: merge login

This links the CLI to your Merge account and stores your session credentials locally.

3. Add Agent Handler to Codex

From the root of the project where you want Codex to reach Pipedrive, run:

merge setup cursor

This writes a Merge CLI section to your project's AGENTS.md file so Codex knows to use the CLI when a task needs Pipedrive data. The command is idempotent, safe to re-run if you need to reset the configuration.

Commit the updated AGENTS.md so the configuration travels with the repo.

4. Authenticate Pipedrive

Create a Codex task that needs live Pipedrive data. For instance: "Read a sample deal with its custom fields and the full pipeline and stage list, then write a sync function that maps Pipedrive deals into our internal schema."

The first time Codex invokes a Pipedrive tool, a Magic Link will appear to complete connector authentication.

Once authenticated, Codex can reach your Pipedrive account through Merge for every later task in this project.

{{this-blog-only-cta}}

Pipedrive MCP FAQ

In case you have more questions on setting up and using the Pipedrive MCP with Codex, we've addressed several more commonly-asked questions below.

What can you do once the Pipedrive MCP is connected to Codex?

With Pipedrive connected, Codex can:

• Read a real deal object, including custom fields, before scaffolding a sync function: pull an actual deal so the mapping code it writes uses the real custom field keys rather than guessed names that don't exist in your account

• Pull the pipeline and stage list before generating stage-transition logic: fetch the real pipeline and stage IDs so the conditionals and state machine it writes reference identifiers that match your account

• Read a person and organization record shape before generating type definitions: retrieve real records so the interfaces or models it writes capture the fields and nesting Pipedrive actually returns

• Pull real activity records before generating test fixtures for a reporting feature: fetch live calls, meetings, and tasks so the fixtures and assertions it produces reflect the data distribution the report will run against

• Read custom field definitions before generating a field-mapping module: fetch the field metadata so the mapping layer it writes resolves the hashed custom field keys to readable names correctly

Why use Merge Agent Handler vs. a self-hosted Pipedrive MCP server?

You can build your own MCP server against Pipedrive's API. For one developer on one account, it's manageable: generate an API token, scope it, and write tool schemas for the endpoints your tasks touch.

It gets harder once more than one person uses it or tasks run in CI.

Each user needs their own token and their own revocation path, and a Pipedrive token carries the full access of the account that issued it, so handing it to an agent without scoping gives that agent everything. There's no central view of which tokens are live or what they can reach.

A self-hosted server doesn't change that. You still own token management and scoping, and now you maintain the server too. Pipedrive doesn't publish an official MCP server, so community builds come with no guarantees on coverage or upkeep.

Merge Agent Handler handles credential storage and token refresh across every connected user. You can scope exactly which Pipedrive operations a Codex task can call, and every call is logged with identity, timestamp, and inputs.

For an agent acting on your CRM data, scoped access plus full audit logging is the foundation you want in place first.

Why connect Pipedrive to Codex?

Pipedrive holds the deal objects, custom field schemas, pipeline and stage definitions, and activity records that CRM integration code has to match exactly.

Codex tasks that write syncs, reporting features, or field-mapping layers need that ground truth to produce code that runs against your account.

The alternative is describing the data model in the prompt, and those descriptions are always a little wrong. A guessed custom field key, a wrong stage ID, or an omitted field is enough to make Codex generate code that fails the first time it touches the real API.

Connecting Pipedrive lets Codex read the actual data when a task needs it. The deal object before a sync, the pipeline IDs before transition logic, the custom field metadata before a mapping layer: Codex works from your account, not a paraphrase of it.

Can I use Merge Agent Handler's Pipedrive MCP with my employees?

Yes, Agent Handler for Employees is built to help organizations provision, secure, and govern how employees connect AI tools like Codex to operational systems like Pipedrive.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which Pipedrive accounts and data types an employee's agent can reach by role or team

• DLP and policy enforcement on tool calls, so admins can block queries that would return sensitive contact or deal data before results reach a Codex task's context

• User-level audit logging so security and IT teams can review which deals, contacts, and activities were accessed, by which employee identity, and when

Taken together, employees can use the Pipedrive MCP to generate syncs against real deal objects, build reporting features grounded in actual activity data, and write field-mapping layers that resolve real custom field keys, and more, while IT keeps centralized control over which data each agent can reach.