By Ira Bodnar, Ryze AI · Updated
Quick answer
To connect Codex to HubSpot, connect HubSpot in a Ryze AI workspace with HubSpot's own sign-in, run codex mcp add ryze --url https://connector.get-ryze.ai/mcp, then run codex mcp login ryze and click Allow connection. Start a new session and ask about your HubSpot contacts or deals.
- In Ryze AI open Integrations, click Connect on HubSpot, choose the portal and approve the permissions
- In your terminal run the codex mcp add command
- Run codex mcp login ryze and sign in on the Ryze AI page
- Allow the workspace, then ask your first HubSpot question
Before you start
- Codex access. OpenAI says ChatGPT Work and Codex are included in the Free, Go, Plus, Pro, Business, Edu and Enterprise plans. Free and Go list Codex in the desktop app only, subject to rollout, so use the desktop steps there. Plus and higher add the CLI and the IDE extension. Codex also runs with an OpenAI API key in the CLI, SDK or IDE extension, billed at API pricing. OpenAI's MCP page names no extra plan for MCP servers.
- HubSpot install rights. A Super Admin or a user with App Marketplace Access can install apps in HubSpot. Anyone else needs a Super Admin to make the connection. HubSpot reports an error at install if the portal's plan misses a scope the app requests.
- A Ryze AI plan or trial. Paid Ads is $89 per month with a 7-day free trial. SEO Starter is $129 per month with a 3-day free trial and adds Content Plan publishing to a HubSpot blog. Agency is $279 per month. The connector itself is free to add; the HubSpot tools need an active plan or trial.
How to connect Codex to HubSpot
Two steps happen in HubSpot and Ryze AI, four in Codex. The connector URL is the same for every user.
Connect HubSpot in Ryze AI
Create a Ryze AI account or sign in, open Integrations, find the HubSpot card and click Connect. Ryze AI sends you to HubSpot to authorize.
Choose the portal and approve the permissions
Sign in to HubSpot, choose the account (portal) and click Choose Account, then approve the permissions HubSpot lists. HubSpot returns you to Ryze AI with the connection saved. For blog publishing only, click View on the HubSpot card, pick the Blog and the Author and click Save.
Add the connector to Codex
Open a terminal and run codex mcp add ryze --url https://connector.get-ryze.ai/mcp. The name ryze is yours to choose. The Codex CLI, the ChatGPT desktop app and the IDE extension share one MCP configuration, so the server shows up in all three.
Sign in from Codex
Run codex mcp login ryze. The browser opens a Ryze AI sign-in page. On a machine without a local browser, add --no-browser, open the printed URL elsewhere and paste the full redirect URL back into the terminal.
Allow the workspace
Sign in on the Ryze AI page if it asks, tick the workspace where you connected HubSpot and click Allow connection. Then run codex mcp list, or type /mcp inside the Codex TUI, to see the server.
Start a new session and ask your first question
Try: Which HubSpot deals were created in the last 30 days? Give me name, amount and stage.
The Ryze AI HubSpot guide covers the HubSpot side of the connection, and the Codex MCP docs cover the client commands.
CLI, desktop app, IDE and config.toml
Codex reaches the Ryze AI connector from every local surface, and all of them share one configuration. Pick the one you work in.
Codex CLI
codex mcp add ryze --url https://connector.get-ryze.ai/mcp
codex mcp login ryzeUse this on your own machine. After login, codex mcp list shows the server and /mcp inside the TUI does the same. With a remote shell, codex mcp login ryze --no-browser prints a URL to open on another device.
ChatGPT desktop app (Codex)
Open Settings, then MCP servers, then Add server. Enter the name ryze, choose Streamable HTTP and enter https://connector.get-ryze.ai/mcp. Save, select Restart, then select Authenticate next to ryze and finish the Ryze AI sign-in. Type /mcp in the composer to view connected servers.
Codex IDE extension
Open the gear menu, then MCP servers, then Add server, with the same name, Streamable HTTP type and URL. Save, select Restart extension, then Authenticate and complete the Ryze AI sign-in. OpenAI notes that plugins are not available in the IDE extension, while MCP servers configured in config.toml are.
config.toml with OAuth
[mcp_servers.ryze]
url = "https://connector.get-ryze.ai/mcp"Edit ~/.codex/config.toml, or a project .codex/config.toml in a trusted project, then run codex mcp login ryze. OAuth is the default for HTTP servers, and Codex supports both client ID metadata documents and dynamic client registration.
config.toml with a Ryze AI API key
[mcp_servers.ryze]
url = "https://connector.get-ryze.ai/mcp"
bearer_token_env_var = "RYZE_API_KEY"Set the RYZE_API_KEY environment variable to the rk_live_ key, which you create in Ryze AI under Workspace Settings, Profile, API keys, Create key. It appears once, so copy it then. Keep it out of repositories and shared shell history.
Timeouts and output size
Codex waits 10 seconds for a server to start (startup_timeout_sec) and 60 seconds for a tool call (tool_timeout_sec). Both can be raised per server in config.toml, which helps with long CRM queries. tools.<tool>.output_token_limit sets an output budget for one tool, which is useful when a list returns many records. This page covers the CLI, the desktop app and the IDE extension; OpenAI's MCP page does not cover Codex cloud tasks, so this guide makes no claim about them.
Claude, ChatGPT and Cursor
The same URL works in other MCP clients. HubSpot is connected once in Ryze AI, so nothing changes on the HubSpot side.
Claude and Claude Code
In Claude on the web or Desktop, open Customize, Connectors, click + Add, choose Add custom connector and enter https://connector.get-ryze.ai/mcp. In Claude Code, use the claude mcp add command from the Claude Code guide linked below.
ChatGPT
OpenAI says full custom MCP server support is for ChatGPT Business and Enterprise/Edu on the web, and Pro can connect custom MCP servers with read and fetch permissions only. Add the URL as a custom MCP server and choose OAuth.
Cursor
Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Cursor runs OAuth with PKCE and asks for approval before using MCP tools by default.
{ "mcpServers": { "ryze": { "url": "https://connector.get-ryze.ai/mcp" } } }HubSpot permissions and scopes
Connecting HubSpot is a standard HubSpot OAuth app install, done in Ryze AI rather than in Codex. Codex never sees your HubSpot password. Three points set how much Codex can reach.
- Who can connect
- A HubSpot Super Admin, or a user holding App Marketplace Access. When the portal's plan lacks a scope the app requires, the install stops with an error message.
- Which portal
- A connection maps to a single HubSpot portal, and HubSpot asks you to pick when your login covers several. Ryze AI documents attaching extra portals to a workspace with View, then Add one more account. The portal marked with a star is the primary and is used unless a prompt names another.
- How far the token reaches
- According to HubSpot, an access token carries the scopes the app asked for, and the installing person's own record restrictions do not narrow it. A user limited to their own contacts who grants a contacts read scope hands over a token that reads every contact. Install with a login whose reach you are willing to share with Codex.
Scopes behind each action
The help center of Ryze AI describes what the agent does after HubSpot is connected. The table pairs each action with the matching scope name from HubSpot's scope reference so you can compare it with the consent screen, which is the final word on the exact list. Tool descriptions refer to custom objects, yet the requested scopes contain no custom-object scope, so plan without them.
| Action in Ryze AI | HubSpot scope |
|---|---|
| Read and edit contacts | crm.objects.contacts.read, crm.objects.contacts.write |
| Read and edit companies | crm.objects.companies.read, crm.objects.companies.write |
| Read and edit deals | crm.objects.deals.read, crm.objects.deals.write |
| Read contact lists | crm.lists.read |
| Look up record owners | crm.objects.owners.read |
| Read and edit CMS blog content | content (HubSpot lists it for CMS Hub Professional or Enterprise, or Marketing Hub Professional or Enterprise) |
Sources: Ryze AI HubSpot guide and HubSpot's scope reference.
Removing access
To cut access from the HubSpot side, uninstall the app under Settings, Integrations, Connected Apps. From Ryze AI, click View on the HubSpot card and use the trash icon on the portal. From Codex, delete the [mcp_servers.ryze] table in config.toml or remove the server in the MCP servers settings.
What Codex can do in HubSpot
Codex gets 5 HubSpot tools through the Ryze AI connector: 3 read, 1 write and 1 delete. All of them act on the portal you connected.
| Tool | Type | What it does |
|---|---|---|
| hubspot__listObjects | Read | Lists CRM records of one object type page by page, with the properties you choose and the IDs of associated records. |
| hubspot__search | Read | Searches CRM records through the HubSpot CRM Search API with filter groups, sorts, a text query and chosen properties. |
| hubspot__read | Read | Sends a GET request to any HubSpot JSON API resource, such as a record, property definitions, owners, a list or blog posts. |
| hubspot__write | Write | Creates or updates a HubSpot resource, such as a contact, company, deal or blog post, and adds associations between records. |
| hubspot__delete | Delete | Archives a HubSpot resource by ID, such as a CRM record or blog post. Most CRM deletes go to HubSpot's recycling bin; deleted blog posts may not be recoverable. |
Codex has its own approval setting per server. In config.toml, default_tools_approval_mode accepts auto, prompt, writes or approve, and writes prompts for tools not marked read-only. Per-tool overrides use tools.<tool>.approval_mode, so setting hubspot__write and hubspot__delete to prompt makes Codex ask before either runs. enabled_tools and disabled_tools work as allow and deny lists; adding hubspot__delete to disabled_tools removes the tool from Codex. Inside the Ryze AI chat the Tool approvals setting begins on Skip all approvals, so switch it to Approve write & delete or Manual approve if you want a prompt there. Ryze AI scheduled tasks have no approval step.
First 3 prompts to run
HubSpot sends back a default subset of properties unless the request lists fields, so every prompt below names the ones it wants. Results come from your own portal, which is why this page describes the output and shows no sample figures.
1. Pipeline check before a standup
Search HubSpot deals that are still open. Return deal name, amount, stage, close date and owner, and show the owner as a name by looking up the owners.
Tools used: hubspot__search on deals, hubspot__read for owners
What comes back: A table of open deals with the fields you listed and an owner name on each row, taken from the records in your portal.
2. New contacts and their companies
List HubSpot contacts created in the last 14 days with first name, last name, email and lifecycle stage, plus the IDs of their associated companies.
Tools used: hubspot__search or hubspot__listObjects on contacts
What comes back: One row per contact with the chosen properties and the IDs of the companies linked to it.
3. Correct one company record
Find the HubSpot company I name next, show its industry and lifecycle stage, and describe the change you would make. Ask me to confirm before you write it.
Tools used: hubspot__search, then hubspot__write
What comes back: The current values and a request for confirmation. The write happens after you answer, and Codex also asks first if you set that tool to prompt.
Deleting uses its own tool, so name the object and the action when you want it, and set hubspot__delete to prompt or disable it in config.toml. The Ryze AI help center says the agent deletes records or blog posts only when explicitly asked.
Ryze AI vs HubSpot's own MCP server
HubSpot runs its own remote MCP server at https://mcp.hubspot.com. HubSpot's documentation names Claude, ChatGPT and Gemini as supported AI clients and does not mention Codex, so treat Codex as untested there. The documentation requires OAuth 2.0 with PKCE, and Codex supports OAuth for HTTP servers, but this guide has not run that pairing.
| Option | Setup | HubSpot coverage | Works in |
|---|---|---|---|
| Ryze AI connector | HubSpot sign-in inside Ryze AI, then codex mcp add with one URL and codex mcp login to sign in | 5 tools: search, list and read records, plus write and delete. CRM contacts, companies and deals, lists, owners and blog content | Codex CLI, desktop app and IDE extension, plus Claude, ChatGPT, Cursor |
| HubSpot remote MCP server | Create an MCP connector in HubSpot under Development, MCP Connectors, then give your client https://mcp.hubspot.com with the client ID and secret. OAuth 2.0 with PKCE is required | 40+ tools across CRM records, activities, content, campaigns, emails and more. Actions respect your HubSpot user permissions | Clients HubSpot documents: Claude, ChatGPT and Gemini. Codex is not mentioned |
HubSpot's own server needs no Ryze AI plan and covers far more HubSpot objects, but you create and manage a connector with client credentials in your portal, and Codex is not on its list of documented clients. Choose it if the work stays inside HubSpot and you are willing to test the pairing. Choose the Ryze AI connector if you want a short tool list, a HubSpot sign-in handled in Ryze AI and one URL for Codex and your other connected platforms; it needs a Ryze AI plan or trial, and your HubSpot data passes through Ryze AI.
HubSpot's remote MCP page did not state a rate limit in the part checked, so confirm limits in your own HubSpot account before running large jobs. The Ryze AI connector has not been tested end to end in Codex during our research, so report any difference you see to Ryze AI support.
Sources: HubSpot remote MCP server, Codex MCP, Codex pricing, Ryze AI HubSpot guide. Checked November 14, 2026.
Errors and fixes
- HubSpot shows an error during the install
- Your HubSpot user is not a Super Admin or lacks App Marketplace Access, or the portal's plan lacks a scope the app requires. Ask a Super Admin to connect HubSpot in Ryze AI, or to grant you the permission.
- codex mcp login cannot open a browser
- Run codex mcp login ryze --no-browser, open the printed URL on another device and paste the full redirect URL back into the terminal.
- The server times out while starting or answering
- Codex allows 10 seconds for startup and 60 seconds per tool call by default. Raise startup_timeout_sec or tool_timeout_sec in the [mcp_servers.ryze] table.
- The server is missing in the desktop app or IDE
- The CLI, desktop app and IDE extension share one configuration. Select Restart (or Restart extension) after adding the server, then select Authenticate.
- The API key is rejected
- Confirm bearer_token_env_var names an environment variable that is set in the shell that starts Codex, that it holds a live rk_live_ Ryze AI key, and that the URL ends in /mcp. Or remove the line and use OAuth.
- No HubSpot tools appear
- Remove the server, add it again and open a new session if you registered it before linking HubSpot. Check that disabled_tools does not list the tool and that enabled_tools, if set, includes it.
- A field is missing from the results
- HubSpot returns a default set of properties unless the request names others. Ask Codex for the exact properties you need.
- The wrong HubSpot portal is connected
- Each connection is one portal. Click View on the HubSpot card in Ryze AI, connect the right portal with Add one more account, then remove the wrong one with the trash icon.
- The HubSpot connection stopped working
- The token may have been revoked, for example if someone uninstalled the app under Connected Apps in HubSpot. Click Reconnect on the HubSpot card and authorize again.
- A read of CMS source code files fails
- Source-code file endpoints return raw files and fail through the read tool. Ask for blog posts or other JSON resources instead.
- Codex says a subscription is required
- The HubSpot tools need an active Ryze AI plan or free trial. Start the trial in Ryze AI and retry.
Frequently asked questions
How do I connect Codex to HubSpot?
Link HubSpot to a Ryze AI workspace first. Then run codex mcp add ryze --url https://connector.get-ryze.ai/mcp and codex mcp login ryze, and finish on the Ryze AI page by choosing the workspace and clicking Allow connection.
Is there a HubSpot Codex connector or MCP server?
HubSpot runs a remote MCP server at https://mcp.hubspot.com with 40+ tools. You create an MCP connector in HubSpot under Development, MCP Connectors, and the server requires OAuth 2.0 with PKCE. HubSpot's documentation names Claude, ChatGPT and Gemini as clients and does not mention Codex. The Ryze AI connector is a separate route with 5 HubSpot tools that Codex reaches through one URL.
Which HubSpot connector should I use with Codex?
Ryze AI is the best HubSpot connector for Codex when you want a HubSpot sign-in handled for you and one URL that also carries your other connected platforms, but it has 5 tools and needs a Ryze AI plan. HubSpot's own server needs no Ryze AI plan and covers many more HubSpot objects, though HubSpot does not document Codex as a client.
Which plan do I need for Codex?
OpenAI includes Codex in the ChatGPT Free, Go, Plus, Pro, Business, Edu and Enterprise plans. Free and Go list it in the desktop app only, subject to rollout. Plus and higher add the CLI and IDE extension. An OpenAI API key also works in the CLI, SDK or IDE extension at API pricing.
What HubSpot permissions do I need?
You need to be a Super Admin or have App Marketplace Access in HubSpot; otherwise a Super Admin has to connect it. The portal must also include every scope the app requires, or HubSpot shows an error during install.
Should I use OAuth or an API key?
OAuth is the default for HTTP servers in Codex and the easier path when you sit at the machine. An API key suits unattended setups. Set bearer_token_env_var to the name of an environment variable that holds the rk_live_ key. The key comes from Workspace Settings, Profile, API keys in Ryze AI and has nothing to do with your HubSpot login.
Can Codex edit or delete HubSpot records?
Yes. The connector has a write tool for contacts, companies, deals and blog posts and a delete tool that archives records by ID. Most CRM deletes go to HubSpot's recycling bin; deleted blog posts may not be recoverable. Set per-tool approval to prompt in config.toml, or list hubspot__delete in disabled_tools, if you want control over each change.
Can I connect more than one HubSpot portal?
Yes. Click View on the HubSpot card in Ryze AI and choose Add one more account. The starred portal is the primary that is used unless you name another, and the tools accept an optional connection_id.
Do the CLI, desktop app and IDE extension need separate setup?
No. OpenAI says the ChatGPT desktop app, Codex CLI and IDE extension share MCP configuration for the same Codex host, so a server added in one appears in the others. You still sign in once through whichever surface you used.
Does this work in Codex cloud tasks?
Unknown. OpenAI's MCP page that this guide relies on does not cover Codex cloud tasks, and the connector was not tested there, so this guide covers only the CLI, desktop app and IDE extension.
How much does it cost?
Connecting the connector is free, but the HubSpot tools need an active Ryze AI plan or free trial. Paid Ads is $89 per month with a 7-day free trial, SEO Starter is $129 per month with a 3-day free trial and Agency is $279 per month. Annual billing takes 30% off the first year.