MCP Gateway · Codex
Connect HubSpot to Codex
When a HubSpot integration misbehaves, the fastest check is to look at what HubSpot actually holds. Codex can read records, owners and property definitions through the Speakeasy MCP Gateway while it works through the failing code. Speakeasy decides on every Codex tool call before it runs, and logins go through the company's existing SSO.
- Category
- Sales & CRM
- Tools
- 13
- Authentication
- OAuth
- Codex
- CLI and ChatGPT desktop app
Behind the MCP Gateway
Run HubSpot MCP behind the MCP Gateway
One URL for every agent, sign-in through your IdP, RBAC down to the tool, and every HubSpot call inspected and logged.
Before you start
What HubSpot needs first
A HubSpot user with access to the Development workspace; an account admin for the first connection does the HubSpot side of the setup.
- The remote MCP server is available to all HubSpot accounts.
- You need a user who can open the Development workspace.
- The first connection should be made by an account admin.
In HubSpot
- Open Development > MCP Connectors.
- Create an MCP connector with the Speakeasy redirect URL.
- Copy the Client ID and Client secret.
Set up
Add HubSpot to Codex in 4 steps
- 01
Add HubSpot from the catalog
An admin finds HubSpot in the MCP Catalog (MCP Gateway > MCP > Catalog) and clicks Add. Speakeasy registers the vendor's server as a remote MCP server and proxies sessions to it. Nothing is copied or re-hosted.
HubSpot uses OAuth. Servers that support dynamic client registration get their OAuth configuration applied automatically.
Where MCP-scoped policies are enabled, the install offers a recommended risk policy for the new server that detects secrets and PII and inspects tool requests and responses.
- 02
Choose who can use HubSpot
Give teams the
mcp:connectscope on the HubSpot server through team access or a role. The organization gateway works out each person's servers from their live access, so granting access adds HubSpot to their gateway on the next call, and removing it takes it away. - 03
Connect Codex
Add the gateway as an MCP server, then log in.
Run the first command with your organization gateway URL.
Run the second command to sign in.
codex mcp add 'speakeasy' \ --url 'https://<organization host>/mcp/gateway/<organization slug>' codex mcp login 'speakeasy' - 04
Sign in and use HubSpot from Codex
The first time Codex connects, it opens a browser so the person can sign in to Speakeasy through your identity provider.
HubSpot needs its own OAuth grant, so each person connects it once. Until they do, HubSpot calls fail while the rest of the gateway keeps working.
From then on, HubSpot's tools appear in Codex, limited to what the person's access allows, and every call lands in the gateway's tool logs.
To roll it out to a team, a ChatGPT workspace admin imports the plugin marketplace under Admin > Plugins and sets an installation policy per role. Imported plugins reach nobody until a policy is set.
Use cases
What Codex users do with HubSpot
Debug a failed owner assignment
HubSpot owner IDs and user IDs are different. When an assignment fails, Codex looks up the owner by email and compares the owner ID with what your code sent.
Verify records after a sync run
After a batch job, Codex fetches the affected contacts by ID and checks that each property and the updated timestamp match what the job should have written.
Validate enumeration values in code
When HubSpot rejects a value, Codex pulls the property's definition and its allowed options, then fixes the constant or mapping that sent the wrong one.
Tools
13 tools
Each HubSpot tool can be allowed or denied per team and role at the MCP Gateway before Codex sees it.
search_crm_objects
Searches and retrieves CRM records from HubSpot based on filters and criteria.
submit_feedback
Collects and submits feedback to HubSpot on dissatisfaction or user request.
get_campaign_contacts_by_type
Get paginated contact IDs for a campaign filtered by attribution type.
search_owners
Lists and searches for owners who can be assigned to CRM records.
get_campaign_analytics
Get campaign analytics (METRICS or REVENUE_ATTRIBUTION) for one or more campaigns. Each entry in the request list is a full analytics request. Each response contains the campaignObjectId of the requested campaign.
get_campaign_asset_types
List the asset type names available as campaign assets (e.g. LANDING_PAGE, BLOG_POST). Use the returned names as the assetType parameter in getCampaignAssetMetrics.
Control
What Speakeasy can see and stop in Codex
The gateway covers every client the same way. The rest depends on what Codex exposes to Speakeasy.
Tool logs
Gateway
Every HubSpot call is logged with the person and the client that made it.
Access by role
Gateway
People reach only the HubSpot tools their team or role allows.
Request and response blocking
Gateway
A risk policy scoped to HubSpot can reject a tool request before it reaches the server, or withhold a result from Codex. MCP-scoped policies are enabled per organization.
Prompt and tool-call blocking
Codex
Agent hooks send each prompt and tool call to Speakeasy, which allows or denies it before Codex runs it.
User attribution
Codex
An [otel] block in ~/.codex/config.toml sends telemetry to Speakeasy. Export is off by default.
Budgets
Codex
Spend limits can block Codex traffic once a budget is reached.
Device agent and MDM
Codex
The device agent keeps Codex's configuration in sync on managed laptops.
- Codex cloud tasks and GitHub code review run off the device. Neither the plugin nor OpenTelemetry covers them; OpenAI's Compliance Logs record them after the fact.
- The workspace rollout needs a ChatGPT Business, Enterprise or Edu admin.
Questions
Frequently asked questions
How does a ChatGPT workspace roll out HubSpot to Codex users?
Which HubSpot accounts can use the MCP server?
How do Codex users get HubSpot?
Are HubSpot calls from Codex logged?
Connect more