How to connect Hermes Agent to HubSpot

Connect your HubSpot portal in Ryze AI once, add one ryze entry to ~/.hermes/config.yaml, run hermes mcp login ryze, then ask Hermes Agent to search deals, list contacts or look up an account owner.

Your MCP URL
https://connector.get-ryze.ai/mcp

Copies the URL for the url field of a ryze entry under mcp_servers in config.yaml. See the steps

See pricing

By Ira Bodnar, Ryze AI · Updated · Sources checked November 14, 2026

Quick answer

The main way to connect Hermes Agent to HubSpot is the Ryze AI connector. Connect your HubSpot portal in Ryze AI with HubSpot's OAuth sign-in, add a ryze entry with the URL https://connector.get-ryze.ai/mcp and auth: oauth under mcp_servers in ~/.hermes/config.yaml, then run hermes mcp login ryze and click Allow connection. Hermes Agent then has 5 HubSpot tools: three that read, one that writes and one that deletes. You create no HubSpot app of your own.

  1. In HubSpot, sign in as a Super Admin or a user with App Marketplace access
  2. In Ryze AI go to Integrations, press Connect on the HubSpot card, pick the portal and approve the permissions screen
  3. Put the ryze entry under mcp_servers in ~/.hermes/config.yaml and run hermes mcp login ryze
  4. Open a new session or run /reload-mcp, then ask Hermes Agent to search your newest deals

Hermes Agent to HubSpot at a glance

FactDetail
Main way to connectThe Ryze AI connector, a remote HTTP MCP server that Hermes Agent reads from one ryze entry under mcp_servers in ~/.hermes/config.yaml
Connector addresshttps://connector.get-ryze.ai/mcp, identical for every user
How Hermes Agent signs inOAuth with auth: oauth, completed once with hermes mcp login ryze. A Ryze AI API key sent as a bearer header from ~/.hermes/.env is the alternative
How HubSpot signs inHubSpot OAuth inside Ryze AI: sign in, choose the portal, approve the permissions. No API key or private app token is pasted anywhere
HubSpot tools5 in all: hubspot__listObjects, hubspot__search, hubspot__read, hubspot__write and hubspot__delete
Changes to the portalYes. The write tool creates or updates records and adds associations, and the delete tool archives a record by ID. Setting trust: untrusted on the ryze entry makes Hermes Agent ask before write-capable calls
Portals per connectionOne. Several portals can sit in one Ryze AI workspace, and the starred one is used unless you name another
Other data in the same chatTools for the other platforms connected in the same Ryze AI workspace appear under the same address. This guide covers HubSpot only
Hermes Agent planNone. Hermes Agent is open source under the MIT license per its GitHub repository and runs on your own machine or server
Ryze AI pricePaid Ads costs $89 per month after a 7-day free trial. Adding the connector costs nothing
HubSpot's own optionA hosted MCP server at https://mcp.hubspot.com. It needs an MCP connector you create in HubSpot, and HubSpot's pages do not name Hermes Agent
Last tested11 read-only HubSpot calls through the connector on November 14, 2026, run from another client. Nothing was run inside Hermes Agent

Before you start

  • Hermes Agent installed. It is open source from Nous Research, licensed MIT per its GitHub repository, and self-hosted, so there is no plan tier to buy. The configuration lives in ~/.hermes/config.yaml.
  • A HubSpot user allowed to install apps. That means Super Admin or App Marketplace access, per HubSpot. Ryze AI is listed in the HubSpot Marketplace. Blog access also depends on the content scope, which HubSpot ties to CMS Hub or Marketing Hub Professional or Enterprise.
  • A Ryze AI workspace with a plan or trial. Paid Ads is $89 per month with a 7-day free trial; SEO Starter is $129 per month (3-day free trial); Agency is $279 per month. The connector itself costs nothing, and annual billing takes 30% off the first year.

How to connect Hermes Agent to HubSpot with OAuth

Two steps happen in HubSpot and Ryze AI, the rest in Hermes Agent. The connector URL is the same for every user.

  1. Check your HubSpot permission

    The person who connects needs to be a Super Admin or have App Marketplace access in HubSpot. Otherwise ask a Super Admin to connect, or to switch on App Marketplace access for your user.

  2. Connect HubSpot in Ryze AI

    Create a Ryze AI account or sign in, open Integrations, find the HubSpot card and click Connect. Sign in to HubSpot, choose the account (portal), click Choose Account and approve the permissions. HubSpot returns you to Ryze AI with the connection saved.

  3. Add the ryze entry to config.yaml

    Open ~/.hermes/config.yaml and add a ryze server under mcp_servers. Editing the file inside a running session starts an automatic MCP reload with a 30-second timeout, which is too short for a browser sign-in, so add the entry and then run the login in the next step.

    mcp_servers: ryze: url: "https://connector.get-ryze.ai/mcp" auth: oauth
  4. Sign in to the connector

    Run hermes mcp login ryze. Hermes Agent prints an authorize URL and opens your browser when it can. Sign in on the Ryze AI page, choose the workspace that holds your HubSpot connection and click Allow connection. Hermes Agent caches the tokens at ~/.hermes/mcp-tokens/ryze.json and reuses them until a refresh fails.

  5. Load the tools

    Start a new session, or run /reload-mcp inside a running one. Hermes Agent registers each tool as mcp_<server>_<tool>, so the HubSpot tools start with mcp_ryze_. If the entry existed before HubSpot was connected, run the login again and start a new session so the tool list refreshes. To see what the server answers, run hermes mcp test ryze.

  6. Ask your first question

    Ask: Search HubSpot deals created in the last 30 days and show name, amount and stage.

The Ryze AI help center page for HubSpot covers the HubSpot side of the connection, and the Ryze AI help article on API keys and the MCP endpoint covers the connector URL. The Ryze AI developers page lists the same URL.

Source for the Hermes Agent steps: Hermes Agent MCP documentation, opened November 20, 2026.

API key, tool filters and headless hosts

Hermes Agent keeps every MCP server in one file, ~/.hermes/config.yaml. These are the variations that matter for this connector.

A Ryze AI API key instead of OAuth

Create a key in Ryze AI under Workspace Settings > Profile > API keys > Create key and copy it, because it is shown once. Put RYZE_API_KEY with the rk_live_ key in ~/.hermes/.env and reference it in the header, since Hermes Agent resolves ${VAR} placeholders in headers from environment variables, which include everything in that file. Run /reload-mcp afterwards. HubSpot stays connected inside Ryze AI, so no HubSpot credential goes into Hermes Agent.

mcp_servers: ryze: url: "https://connector.get-ryze.ai/mcp" headers: Authorization: "Bearer ${RYZE_API_KEY}"

Show Hermes Agent only the read tools

Each server entry accepts tools.include and tools.exclude. This entry registers the three HubSpot read tools and nothing else from the connector, which also hides the tools of every other platform in the workspace. It hides tools from Hermes Agent only and HubSpot does not enforce it.

mcp_servers: ryze: url: "https://connector.get-ryze.ai/mcp" auth: oauth tools: include: - hubspot__listObjects - hubspot__search - hubspot__read

A remote or headless host

When Hermes Agent runs on a server and your browser is on another machine, the local callback cannot reach the browser. The Hermes Agent documentation lists these ways around it: paste the redirect URL back at the prompt, forward the callback port over SSH, or complete the sign-in from the Desktop app or dashboard. It also names a device-code flow (hermes mcp login ryze --flow device), which works only when the authorization server advertises a device endpoint. This guide did not check whether the Ryze AI connector does.

hermes mcp login ryze

The messaging gateway and unattended runs

A running gateway never opens a browser, so sign in with hermes mcp login ryze first. A server whose first connect failed because no token was cached waits for a login.

Reloading and timeouts

Hermes Agent waits for the browser sign-in for 5 minutes, and oauth.timeout on the entry makes it wait longer. connect_timeout on the entry bounds the first connection. The pages read for this guide give no default for the length of a tool call.

mcp_servers: ryze: url: "https://connector.get-ryze.ai/mcp" auth: oauth oauth: timeout: 600 connect_timeout: 60

Hermes Agent and MCP: the facts in one table

TopicWhat the Hermes Agent documentation says
Where servers are added~/.hermes/config.yaml under mcp_servers, or with hermes mcp install for the catalog of Nous-approved servers. The catalog examples on the documentation page are deepwiki, linear and github, and the page names no HubSpot entry
TransportsLocal stdio servers (command and args) and remote HTTP servers (url)
Sign-inauth: oauth does the browser sign-in. Hermes Agent identifies itself with a Client ID Metadata Document on servers that support one and falls back to dynamic client registration on those that do not. Static bearer headers also work
Token storage~/.hermes/mcp-tokens/<server>.json, written with restricted permissions and reused until refresh fails
Tool namesmcp_<server_name>_<tool_name>, so a server named ryze registers its tools under names that start with mcp_ryze_
ApprovalA server entry can set trust: untrusted so that write-capable calls ask first. Tools annotated readOnlyHint stay unprompted. /yolo, --yolo and approvals.mode: off skip that prompt
Filteringtools.include and tools.exclude per server, with glob patterns. enabled: false skips a server. hermes mcp configure opens a checklist of the tools
Reload/reload-mcp, or a new session. Editing config.yaml inside a running CLI session reloads MCP with a 30-second timeout
ProxiesHTTP and SSE servers honor HTTPS_PROXY, HTTP_PROXY, ALL_PROXY and NO_PROXY
PlanNone. Open source, self-hosted

Sources: Hermes Agent MCP documentation, NousResearch/hermes-agent on GitHub. Opened November 20, 2026.

Other clients

The same URL works in other MCP clients. HubSpot is connected once in Ryze AI, so nothing changes on the HubSpot side.

Claude Code and Codex

Claude Code takes claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp and Codex takes codex mcp add ryze --url https://connector.get-ryze.ai/mcp. See [How to connect Claude Code to HubSpot](/how-to-connect-claude-code-to-hubspot) and [How to connect Codex to HubSpot](/how-to-connect-codex-to-hubspot).

Claude and ChatGPT

Claude adds the URL under Customize > Connectors. In ChatGPT the full custom MCP flow is for Business and Enterprise/Edu plans, and Pro users get read and fetch permissions only. See [How to connect Claude to HubSpot](/how-to-connect-claude-to-hubspot) and [How to connect ChatGPT to HubSpot](/how-to-connect-chatgpt-to-hubspot). If the connector was added before HubSpot was connected, remove and re-add it, then start a new chat.

Cursor

Cursor reads the same URL from its mcp.json file. See [How to connect Cursor to HubSpot](/how-to-connect-cursor-to-hubspot).

HubSpot scopes and Hermes settings

What the connection can reach is set by the HubSpot install made in Ryze AI. Hermes Agent only authenticates to the Ryze AI connector. Four points explain the access.

The install is an OAuth app
You sign in to HubSpot, pick a portal and approve the permissions screen. No key or private app token is pasted. Ryze AI's Marketplace listing names eight shared data types: Contacts, Contact Properties, Companies, Deals, Deal Properties, Contact Lists, Owners and CMS Blog Post.
Installer rights
HubSpot requires Super Admin or App Marketplace access permissions for any install. A user without either asks a Super Admin.
Token scopes beat user rights
Per HubSpot's OAuth guide, an access token carries the scopes the app asked for, not the installer's own record rights. Someone limited to owned contacts who approves crm.objects.contacts.read hands the app a token that can view every contact.
Hermes-side settings
trust, tools.include and tools.exclude on the ryze entry choose which tools Hermes Agent sees and when it asks. They live on your machine and leave the HubSpot scopes unchanged.

The HubSpot scopes behind the connection

Hermes Agent authenticates to the connector, whose discovery data lists the scopes mcp:read and mcp:write for that step. Separately, the HubSpot install needs the scopes below. Ryze AI's facts call these required: contacts, companies and deals read and write, owners read, contact and deal schemas, lists read and content. Files, CMS functions, knowledge base and membership are optional. Descriptions are shortened from HubSpot's scopes reference.

HubSpot scopeWhat it coversAvailability per HubSpot
crm.objects.contacts (read, write)Contact properties and details; write adds create, delete and change.All accounts
crm.objects.companies (read, write)The same for companies.All accounts
crm.objects.deals (read, write)The same for deals.All accounts
crm.objects.owners.readWhich users are assigned to records.All accounts
crm.schemas.contacts.read, crm.schemas.deals (read, write)Property settings for contacts and deals.All accounts
crm.lists.readContact lists, read only.All accounts
contentWebsite page, landing page and blog APIs.CMS Hub or Marketing Hub, Professional or Enterprise

Which optional scopes the Ryze AI consent screen requests was not opened for this guide. Read the list HubSpot displays before approving.

Outside the default connection: ticket records (the test ticket search returned status not_allowed), custom objects (no custom-object scope is requested), editing list membership, and CMS theme or template source files, which come back as raw files and fail in the read tool. Another portal needs a separate connection.

Sources: HubSpot scopes, OAuth guide, installing apps, Ryze AI listing in the HubSpot Marketplace. Checked November 14, 2026. Which scopes Ryze AI asks for comes from the Ryze AI HubSpot facts.

Removing access

To remove access, disconnect HubSpot on its Ryze AI card or uninstall the Ryze AI app in HubSpot. On the Hermes Agent side, set enabled: false on the ryze entry or delete it, and remove ~/.hermes/mcp-tokens/ryze.json to drop cached tokens.

What Hermes Agent can do in HubSpot

There are 5 HubSpot tools in the Ryze AI connector. On November 14, 2026 all five definitions were loaded by name and matched Ryze AI's facts. Hermes Agent lists them with the mcp_ryze_ prefix.

ToolTypeWhat it does
hubspot__listObjectsReadPages through the records of one CRM object type, returning the properties you pick and associated record IDs. Limit up to 100.
hubspot__searchReadRuns the HubSpot CRM Search API with filter groups, sorts, a text query and chosen properties. Limit up to 200. Operators in the definition: EQ, NEQ, GT, GTE, LT, LTE, BETWEEN, IN, NOT_IN, HAS_PROPERTY, NOT_HAS_PROPERTY, CONTAINS_TOKEN.
hubspot__readReadA GET against any HubSpot JSON API resource: a record, property definitions, owners, a list or blog posts. CMS source-code file paths fail.
hubspot__writeWriteCreates or updates a resource (contact, company, deal, blog post) and can add associations.
hubspot__deleteDeleteArchives a resource by ID. Most CRM deletes land in HubSpot's recycling bin; deleted blog posts may stay gone.

Approvals in Hermes Agent

In Hermes Agent, approval for MCP tools is set per server. Adding trust: untrusted to the ryze entry makes every write-capable call on that server ask first, and tools annotated readOnlyHint stay unprompted. The documentation names no default for an entry without a trust key, so set it explicitly if you want the prompt. /yolo, --yolo and approvals.mode: off skip the prompt. Whether the Ryze AI tools carry the readOnlyHint annotation was not checked, so expect prompts on some reads as well. Separately, the Ryze AI chat has its own Tool approvals setting that starts on Skip all approvals, with Approve write & delete and Manual approve available, and scheduled tasks run without an approval step.

mcp_servers: ryze: url: "https://connector.get-ryze.ai/mcp" auth: oauth trust: untrusted

HubSpot limits in numbers

HubSpot counts API use per account and gives search its own caps. Ryze AI's facts do not map its connection onto these quotas, and no test response carried a rate limit header, so read the figures as HubSpot's published limits, in HubSpot's units. The first row is the rule HubSpot gives OAuth apps distributed through its Marketplace; no HubSpot page applies it to Ryze AI by name.

LimitNumber
Marketplace OAuth app burst110 requests per 10 seconds for each account that installs the app, excluding CRM Search. The limit increase add-on does not raise it
CRM Search rate5 requests a second per account
Search pagingDefault 10 per page, maximum 200, and 10,000 results in total for one query. A request for 201 returned Error 400 VALIDATION_ERROR in the test
Search shapeUp to 5 filterGroups of 6 filters each, request body up to 3,000 characters
Search freshnessNew or edited records can take a moment to show up, and archived records are never returned
Over the limitHubSpot answers 429 until the window passes; the daily limit resets at midnight in the account time zone
Token lifeOAuth access tokens last 30 minutes and are refreshed with the refresh token
Restoring deletesRecords can be restored from the recycling bin for 90 days; GDPR or permanent deletion skips it and can take up to 30 days to purge

Sources: usage guidelines, CRM search API, OAuth guide, restoring deleted records. Checked November 14, 2026.

Tested calls

These calls ran through the Ryze AI connector on November 14, 2026, from another MCP client, against an already connected portal. They were read-only. No record, name or ID from the portal is shown.

CallWhat came back
hubspot__search on contacts, companies and deals, filtered on a random string (3 calls)Each returned {"total":0,"results":[]}, a valid empty result.
hubspot__search with a limit of 201Refused: limit must be in range [0..200], Error 400, category VALIDATION_ERROR.
hubspot__search on a property that does not existRefused with There was a problem with the request. (Error 400).
hubspot__search on ticketsRefused with status not_allowed.
hubspot__listObjects on contacts with a limit of 1One result with its id, properties, createdAt, updatedAt, archived and url, plus a paging block with an after value.
hubspot__read on made-up IDs for a deal, a contact and a blog post (4 calls)All came back as status not_found, two of them as an HTML 404 page.

First 3 prompts to run

Each answer comes from your own portal, so this page describes what comes back instead of showing sample records. Hermes Agent picks the tool itself; the names are listed so you can check which one ran.

1. Newest deals

Search HubSpot deals created in the last 30 days and show the deal name, amount and stage, 50 per page.

Tools used: hubspot__search

What comes back: Deals from your portal with the three properties named. A search with no match returns a total of 0.

2. One company and its links

Find the HubSpot company with the domain example.com, then list its associated contacts and deals.

Tools used: hubspot__search, hubspot__listObjects

What comes back: The company record plus IDs of linked contacts and deals. HubSpot sends its default property set unless you name fields.

3. Property names before a filter

Read the contact property definitions from HubSpot and list the internal names of the lifecycle and lead status properties.

Tools used: hubspot__read

What comes back: The contact property definitions. A filter on a name that does not exist is rejected, so these internal names are the safe input for later searches.

When you want a change, describe it in plain words. With trust: untrusted on the ryze entry, Hermes Agent asks before it runs a write-capable call. Replace the names in the prompts with ones from your portal.

10 jobs to hand to Hermes Agent

Ten requests for Hermes Agent, each with the Ryze AI tool behind it. The last column is the fact pack's view of the default connection. All of them need an active Ryze AI plan or trial, and the test only ran searches and a list.

JobAsk Hermes AgentToolWorks on the default connection
Look up one personFind the contact with this email and show the properties I name.hubspot__searchYes. A contacts search ran and came back empty but valid
New dealsShow deals from the last 30 days with name, amount and stage.hubspot__searchYes. A deals search ran
Stuck dealsFind open deals untouched for 30 days and name each owner.hubspot__search, then hubspot__read on crm/v3/ownersSearch ran; owner read did not
Account viewTake a company by domain and list the contacts and deals tied to it.hubspot__search, then hubspot__listObjectsCompany search ran; associations were not requested
Contact pagingWalk through contacts with lifecycle stage and create date.hubspot__listObjectsYes. One record came back with a paging cursor
Field namesList contact and deal properties so I can write a correct filter.hubspot__read on crm/v3/properties/contacts or dealsYes by the facts. Not run
Read a listShow the details of this contact list.hubspot__read on crm/v3/lists/{listId}Reading yes, editing no. Not run
New deal recordCreate a deal and associate it with this company and contact.hubspot__writeYes by the facts. Not run, since it edits the portal
Fix a propertySet this property on a contact, company or deal.hubspot__writeYes by the facts. Not run
Remove a duplicateDelete the duplicate contact with this ID; I confirm.hubspot__deleteYes by the facts, by ID. Not run. With trust: untrusted Hermes Agent asks first

Left out by Ryze AI's facts: tickets, custom object records, adding contacts to a list and reading theme or template code. Blog posts are in the facts, but both blog reads in the test used made-up IDs and got an HTML 404, so blog support on each portal tier is unconfirmed.

5 ways to connect Hermes Agent to HubSpot

Five ways can give Hermes Agent your HubSpot data. This guide treats the first, the Ryze AI connector, as the main way: HubSpot is joined by OAuth in Ryze AI, you create no HubSpot app, and Hermes Agent holds one address and a browser sign-in. The others were read on their own pages on November 14, 2026. None was run in Hermes Agent, which accepts any remote HTTP MCP server by url, so each setup cell says what the vendor page states and how it would fit config.yaml.

WayRuns whereSetup in Hermes AgentWhat it reaches in HubSpotPrice
Ryze AI connector (the main way)Hosted by Ryze AI, one address for every userConnect HubSpot in Ryze AI, then a ryze entry with url and auth: oauth plus hermes mcp login ryze. A Ryze AI API key in a bearer header from ~/.hermes/.env also works5 tools covering contacts, companies and deals, with owners, property definitions, lists and blog posts via the read tool. One portal per connectionFree to connect. Tools need a plan or trial: Paid Ads $89 per month with a 7-day free trial, SEO Starter $129 per month, Agency $279 per month
HubSpot remote MCP serverHosted by HubSpot at https://mcp.hubspot.comCreate an MCP connector in HubSpot (Development, MCP Connectors) with a name and redirect URL; HubSpot issues a client ID and secret. The client must support OAuth with PKCE. HubSpot does not name Hermes Agent and the pairing was not tested36 documented tools on November 14, 2026, including CRM search, activities, blog and landing pages, campaigns and analytics. No delete tool is listedNo price on the page
ComposioHosted at https://connect.composio.dev/mcpLink HubSpot inside Composio (managed OAuth, your own app or an API key), then add the address as a url entry and authenticate. The Composio pages seen name other clients, not Hermes Agent354 tools and 2 triggers in the HubSpot toolkit, with batch create, update and archiveFree tier with 10,000 tool calls a month; Standard $18 per seat per month. The toolkit FAQ quotes another free allowance
Zapier MCPHosted by ZapierBuild a Zapier MCP server, enable HubSpot actions and sign in. Hermes Agent is absent from the client lists seenOnly the HubSpot actions you enable; Zapier prints no totalEach successful call uses 2 tasks of the Zapier plan
Windsor.ai MCPHosted by Windsor.aiAdd HubSpot as a Windsor data source, then Windsor MCP to the assistant. Its guides name other clients, not Hermes AgentReporting on 1,141 HubSpot fields (287 metrics, 854 dimensions); writes are not statedOn every plan; free plan with 1 user, 1 data source and 1 account

HubSpot's server has 36 tools to the Ryze AI connector's 5, and HubSpot says its connectors for Claude, Microsoft Copilot, Gemini and ChatGPT run on it. In exchange it wants a client ID and secret that you create. Hermes Agent allows several servers side by side in config.yaml, so a ryze entry and a hubspot entry can coexist. Ryze AI's earlier post, How to connect Google and Meta Ads with Hermes Agent, uses Composio for ad platforms instead.

HubSpot options that do not fit Hermes Agent

  • HubSpot's own connectors for ChatGPT, Claude, Gemini and Copilot. Each installs inside its assistant and does not run in Hermes Agent. Gemini's is read-only and needs paid Google Workspace.
  • HubSpot Developer MCP server. A local server from hs mcp setup with 23 developer-docs and project tools and no CRM record tools. HubSpot lists Gemini CLI, Claude Code, Codex CLI, Cursor, VS Code and Windsurf, not Hermes Agent.
  • @hubspot/mcp-server on npm. The older local beta server (21 tools, private app token), last published as 0.4.0 in June 2025. HubSpot stopped new legacy private apps from September 28, 2026.
  • HubSpot Agent CLI. A beta command-line tool with a dry-run mode that handles CRM records. HubSpot names Claude Code, Claude Cowork and OpenAI Codex; Hermes Agent is not named.
  • Coupler.io MCP. Read-only analysis of datasets your own Coupler.io flows load. Its pages disagree on which plan includes it.

Which one to pick

Ryze AI is the best way to connect Hermes Agent to HubSpot for searching and editing contacts, companies and deals behind one URL with no HubSpot app of your own, with three caveats: 5 tools against HubSpot's 36, no tickets, custom objects or list editing, and a Ryze AI plan once the trial ends. Choose HubSpot's server if you want the wider tool list and will create the MCP connector and test the sign-in yourself. Choose Composio or Zapier if you already pay for them, and Windsor.ai for reporting.

Sources: HubSpot remote MCP server, HubSpot MCP overview, Developer MCP server, Agent CLI, @hubspot/mcp-server on npm, Composio HubSpot toolkit, Composio pricing, Zapier MCP for HubSpot, Windsor.ai HubSpot fields, Coupler.io MCP for HubSpot, Hermes Agent MCP documentation. Checked November 14, 2026.

Hermes Agent, HubSpot and MCP: dates that matter

DateWhat happened
June 18, 2025@hubspot/mcp-server 0.4.0 was published; it was still the latest on November 14, 2026.
April 13, 2026HubSpot's remote MCP server reached general availability for all accounts, with writes and OAuth with PKCE.
June 29, 2026Content analytics and landing page creation arrived in the remote MCP server.
September 15, 2026The Fall 2026 Spotlight added custom objects, activable objects and Leads to HubSpot's MCP server and Claude connector.
October 26, 2026Creating legacy private apps was disabled for existing HubSpot accounts (September 28 for new ones), with Service Keys as the replacement.
November 20, 2026Hermes Agent's MCP documentation was read for this guide. It can change between builds, so run hermes mcp test ryze after an update.

Sources: Hermes Agent MCP documentation, remote MCP generally available, Fall 2026 Spotlight, legacy private app sunset, @hubspot/mcp-server on npm. Checked November 14, 2026.

How this guide was tested

On November 14, 2026, 11 read-only HubSpot calls were run through the Ryze AI connector from another MCP client against an already connected portal, and the HubSpot pages named on this page were opened. The Hermes Agent documentation was read on November 20, 2026. Nothing about the portal or its records is recorded here.

What was runWhat came back
Connector tool list, November 14Five definitions loaded by name from the connector and matched Ryze AI's facts. Each takes a workspace argument and an optional connection_id.
Eleven read-only callsSearches, one list and reads by ID. The tested calls table above says what each returned.
Hermes Agent MCP documentation, November 20Source of every Hermes Agent step here: auth: oauth, hermes mcp login, the token cache, /reload-mcp, tool filters and trust.
Writes and deletesNot run, so no change to a portal is claimed.

Not run for this guide: anything inside Hermes Agent, any write or delete call, owner, property definition and list reads, and any existing blog post read. Hermes Agent was not installed, so hermes mcp login ryze and the config.yaml entries follow its documentation as read on November 20, 2026. The Ryze AI connector lists a registration endpoint and no metadata document, and Hermes Agent falls back to dynamic client registration, so the sign-in should fit, but that was not run. The Ryze AI help center has no page for Hermes Agent, and Ryze AI was not tested there.

Hermes Agent and HubSpot errors and fixes

The messages in the table came back from the November 14, 2026 test calls through the Ryze AI connector, with IDs removed. No call was run from Hermes Agent, so the Hermes fixes follow its documentation.

Messages seen in the test calls

All five were returned by the test calls on November 14, 2026.

Message or codeWhat it meansWhat to do
limit must be in range [0..200] (actual value: 201), Error 400, category VALIDATION_ERRORSearch pages hold 200 records at most.Request 200 or fewer and continue with the after value.
There was a problem with the request. (Error 400)The search body was rejected without naming the bad field. The test filtered on a property that does not exist.Read crm/v3/properties/contacts and filter on an internal name.
The scope needed for this API call isn't available for public use. If you have questions, contact support or post in our developer forum. (status not_allowed)The default connection could not search tickets on the test portal.Stay with contacts, companies and deals, or use HubSpot's own connector for tickets.
Object not found. objectId is usually positive. (status not_found)No record has that ID; the test used 0.Search first and reuse the returned id.
provider returned text/html;charset=iso-8859-1 (status 404) "Error 404 Not Found" (status not_found)HubSpot replied with an HTML 404 page, which the JSON-parsing read tool reported. It appeared for a contact path and twice for a blog post path with made-up IDs.Check the ID; find contacts by email or list blog posts for a real ID.

Other problems

The tools do not show up in Hermes Agent
Start a new session or run /reload-mcp, then hermes mcp test ryze to see the server's answer. Check for a tools.include or tools.exclude filter and for enabled: false. If HubSpot was connected after the login, log in again and open a new session.
The browser sign-in times out
A config.yaml edit inside a running session reloads MCP with a 30-second timeout, too short for OAuth. Add the entry, then run hermes mcp login ryze in a fresh terminal. Set oauth.timeout if you need more than 5 minutes.
Hermes Agent cannot reach the callback on a server
Paste the redirect URL back at the prompt, forward the callback port over SSH, or sign in from the Desktop app or dashboard.
A 401 or 403 from the connector
Run hermes mcp login ryze again. With an API key, check RYZE_API_KEY in ~/.hermes/.env and a header of Bearer plus the rk_live_ key.
HubSpot blocks the approval
Only Super Admins and users with App Marketplace access can install. Ask a Super Admin to connect or to grant you the permission.
A new record is missing from search
HubSpot says fresh or edited records take a moment to appear, and archived ones never do. Retry shortly.
Properties come back empty
HubSpot sends only a default subset. Name the properties you want by internal name.
You need a second portal
In Ryze AI click View on the HubSpot card, then Add one more account, and say which portal you mean in the prompt.
Blog calls fail
HubSpot limits the content scope to CMS Hub or Marketing Hub Professional or Enterprise, and blog reads were not confirmed in the test.
The tools say a subscription is required
The HubSpot tools need an active Ryze AI plan or trial. Start the trial and retry.
Requests fail behind a proxy
HTTP servers honor HTTPS_PROXY, HTTP_PROXY and NO_PROXY, so set them in the environment Hermes Agent starts from.

Terms on this page

Hermes Agent
An open source AI agent from Nous Research that runs on your own machine or server. Its MCP servers live in ~/.hermes/config.yaml under mcp_servers.
MCP
The Model Context Protocol, an open standard for letting an AI model call tools on outside servers. The Ryze AI connector is a remote MCP server.
Portal
HubSpot's word for an account. One Ryze AI connection covers one portal.
Scope
A permission an app requests when installed; each opens certain HubSpot API endpoints.
Install rights
Super Admin or App Marketplace access, the two HubSpot permissions that allow adding an app.
Filter group
A set of CRM search filters joined by AND; groups are joined by OR, up to 5 groups of 6 filters.
Recycling bin
Holding place for deleted CRM records, restorable for 90 days.

Sources: CRM search API, installing apps, Hermes Agent MCP documentation. Checked November 14, 2026.

Frequently asked questions

How do I connect Hermes Agent to HubSpot?

Connect HubSpot in Ryze AI under Integrations with its OAuth sign-in, then add a ryze entry with the URL https://connector.get-ryze.ai/mcp and auth: oauth under mcp_servers in ~/.hermes/config.yaml. Run hermes mcp login ryze, click Allow connection, then start a new session or run /reload-mcp.

Is there a HubSpot MCP connector for Hermes Agent?

Yes, the Ryze AI connector at https://connector.get-ryze.ai/mcp. It is a remote MCP server with 5 HubSpot tools, and Hermes Agent supports remote HTTP servers with OAuth. HubSpot's own connectors are for ChatGPT, Claude, Gemini and Copilot, and its pages do not name Hermes Agent.

Is there a HubSpot MCP server for Hermes Agent?

HubSpot runs a remote MCP server at https://mcp.hubspot.com with 36 tools, but its pages do not name Hermes Agent and it needs a client ID and secret from an MCP connector you create in HubSpot. Whether it works with Hermes Agent's sign-in was not tested here.

Which should I use, Ryze AI or HubSpot's own server?

The Ryze AI connector needs no HubSpot app and puts HubSpot next to other platforms on the same URL, but it has 5 tools and leaves out tickets and custom objects. HubSpot's own server has 36 tools and needs a connector you create, and its pairing with Hermes Agent was not checked.

Does Hermes Agent have a HubSpot MCP server built in?

The Hermes Agent documentation page read for this guide names no HubSpot entry. Its catalog examples are deepwiki, linear and github. Add HubSpot through a url entry in config.yaml, such as the Ryze AI connector.

Who can connect HubSpot to Ryze AI?

Super Admins and users with App Marketplace access can. Everyone else needs a Super Admin, because HubSpot allows no other user to install an app.

Can Hermes Agent change my HubSpot records?

Yes. The write tool creates or updates contacts, companies and deals and adds associations between records. To have Hermes Agent ask first, set trust: untrusted on the ryze entry. No write call was run for this guide.

Can Hermes Agent delete things in HubSpot?

Yes, if you name the ID. The delete tool archives the record. Most CRM deletes go to HubSpot's recycling bin, which restores them for 90 days, while a deleted blog post may be gone for good.

How do I make it read-only?

List the three read tools under tools.include on the ryze entry, which hides the write and delete tools from the agent. HubSpot does not enforce that, because the Ryze AI install holds the write scopes.

Does Hermes Agent need a paid plan for MCP?

No. Hermes Agent is open source under the MIT license per its GitHub repository and self-hosted. The Ryze AI side needs a plan or trial for the HubSpot tools: Paid Ads at $89 per month with a 7-day free trial.

Should I use OAuth or an API key?

Use OAuth when you can open a browser, because hermes mcp login ryze handles the sign-in and Hermes Agent refreshes the tokens. Use a Ryze AI API key in a bearer header for servers and scripts where nobody can click Allow connection.

Does it work on a headless server or a VPS?

Yes, with an extra step for the sign-in. Paste the redirect URL back at the prompt, forward the callback port over SSH, or use the Desktop app or dashboard. An API key avoids the browser entirely.

Can I use several HubSpot portals?

Yes. Each connection is one portal, and a Ryze AI workspace can hold several. The starred portal answers unless your prompt names another, and the tools take an optional connection_id.

Does it reach HubSpot tickets or custom objects?

Not by default. The test ticket search returned status not_allowed, and no custom-object scope is requested. Stick to contacts, companies and deals, or use a HubSpot connector built for tickets.

Why do the HubSpot tools not show up in Hermes Agent?

Start a new session or run /reload-mcp, then run hermes mcp test ryze. Check that no tools.include or tools.exclude filter hides them and that the entry is not set to enabled: false. Also confirm that HubSpot is connected in Ryze AI before the login.

How much does it cost?

Adding the connector is free. The HubSpot tools need 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, Agency is $279 per month, and annual billing takes 30% off the first year. Hermes Agent itself is free software.

How do I disconnect HubSpot from Hermes Agent?

Set enabled: false on the ryze entry or delete it from config.yaml, and delete ~/.hermes/mcp-tokens/ryze.json. To remove HubSpot access itself, disconnect HubSpot on its card in Ryze AI or uninstall the Ryze AI app inside HubSpot.

Sources

Checked November 14, 2026.

Connect HubSpot to Hermes Agent

One Ryze AI connection gives Hermes Agent 5 HubSpot tools. Paid Ads is $89 per month with a 7-day free trial; annual billing takes 30% off the first year.

HubSpot MCP server

Need help? Read the Ryze AI HubSpot guide or email Ryze AI support.