How to connect HubSpot MCP with Codex (4 steps)

When you hand Codex a task that touches HubSpot, you usually paraphrase the CRM's shape into the task description.

Codex generates code against your interpretation instead of the actual schema. Small gaps turn into wrong internal property names, invalid stage IDs, and syncs that compile against assumptions rather than the real object model.

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

How it works

Merge Agent Handler connects Codex to HubSpot's CRM 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 third-party services.

Once connected, Merge manages your HubSpot OAuth credentials and token refresh on your behalf, so no token state lives in your repo or local environment.

Related: How to use the HubSpot 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 HubSpot account with admin or API access

If you want to connect Merge Agent Handler's HubSpot 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 your installation: merge --version

2. Log in to Merge

Authenticate the CLI with your Merge Agent Handler account: merge login

This links the CLI to your account so Merge can make authorized requests against HubSpot on your behalf.

3. Add Agent Handler to Codex

Run the following from the root of the project where you want Codex to have access to Merge tools:

merge setup agents-md

This writes a Merge CLI section to your project's AGENTS.md file so Codex knows to use the CLI when it needs to call third-party services. The command is idempotent, so it's safe to re-run if you need to reset. Commit the updated AGENTS.md so the configuration travels with the repo.

Related: A guide to integrating the HubSpot MCP with Cursor

4. Authenticate HubSpot

Create a Codex task that requires HubSpot data, something like:

Read our deal properties from HubSpot and generate the TypeScript types and a parser for the deal object, using the real internal property names and enum values.

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

{{this-blog-only-cta}}

HubSpot MCP FAQ

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

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

With HubSpot connected, Codex can:

• Read property definitions before generating models: pull an object's property schema so the types and field names it emits match HubSpot's internal names, not the UI labels

• Pull pipeline configuration before writing stage logic: read the real pipeline and stage IDs so generated stage-transition code uses valid IDs instead of hardcoded labels

• Read association types before generating traversal code: fetch the association schema so the code Codex writes walks related records using the correct association type IDs

• Pull a sample record to generate an accurate parser: read a real contact or deal so the parser it scaffolds handles the actual response shape and property types

• Read enumeration options before writing validation: pull an enumeration property's defined options so generated validation and type unions cover the real values

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

You can self-host a HubSpot MCP server with open-source packages that wrap the HubSpot API. For a solo developer running local tasks against their own portal, that setup works.

The overhead compounds once tasks run across a team and a shared repo.

HubSpot auth means managing private app tokens or OAuth credentials and keeping them fresh, and there's no built-in way to scope which objects or operations an autonomous agent can reach.

Merge Agent Handler centralizes authentication and adds a control layer on top.

You define which HubSpot operations Codex is allowed to call, Merge enforces those boundaries, and every tool call is logged with a full audit trail. For an agent that acts on its own, that scoping and observability is what makes the deployment defensible rather than just functional.

Why connect HubSpot to Codex?

Autonomous coding agents are only as accurate as the context they're given.

When the schema is summarized into a task description, Codex fills the gaps with assumptions, and stale details lead to wrong internal property names, invalid stage IDs, and incorrect association logic.

Connecting HubSpot to Codex removes the guesswork.

Codex reads the actual properties, pipelines, and associations while it generates code, so its output reflects the current CRM schema instead of a paraphrase written days earlier.

Can I use Merge's HubSpot MCP with my employees?

Yes, Merge for Workforce is built to help organizations provision, secure, and govern how employees connect AI to systems like HubSpot.

Common patterns include:

• Provisioning and access control via SCIM with identity providers like Okta and Microsoft Entra ID, so IT can manage which employees can read or edit HubSpot records by role or team

• DLP and policy enforcement on tool calls, so admins can block queries that would return sensitive customer or revenue data before results reach the employee's AI session

• User-level audit logging so security and IT teams can review which records were viewed, created, or updated, by which employee identity, and when

Put together, employees can use the HubSpot MCP to look up records, generate code from the CRM schema, update objects, and more, while IT keeps centralized control over which objects and operations each identity can reach.