How to connect Windsurf to HubSpot

Connect your HubSpot portal once in Ryze AI, add one MCP URL to the Windsurf (Devin Desktop) MCP config, sign in, then ask the editor agent about contacts, companies, deals and blog posts.

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

Copies the URL. Use it in Customize, MCPs, or with devin mcp add. See the steps

See pricing

By Ira Bodnar, Ryze AI · Updated · Connector tested November 14, 2026

Quick answer

The main way to connect Windsurf to HubSpot is the Ryze AI connector. Approve HubSpot once inside Ryze AI with HubSpot's own sign-in, then put "ryze": {"url": "https://connector.get-ryze.ai/mcp"} under mcpServers in ~/.config/devin/mcp_config.json. Sign in with the Authenticate button in Devin Desktop, or with devin mcp login ryze in Devin CLI, click Allow connection, and the agent has 5 HubSpot tools for contacts, companies, deals, owners, lists and blog posts.

  1. In Ryze AI open Integrations, find HubSpot and click Connect
  2. Sign in to HubSpot, choose the portal and approve the permissions
  3. In Windsurf open Customize, then MCPs, and add the ryze server with the connector URL
  4. Click Authenticate (devin mcp login ryze in Devin CLI), then Allow connection, and ask for the deals created this month

Windsurf to HubSpot at a glance

FactDetail
Main way to connectThe Ryze AI connector, kept in Devin's mcp_config.json as one url entry named ryze, or added with devin mcp add in Devin CLI
Server addresshttps://connector.get-ryze.ai/mcp. The same address serves every platform connected in the Ryze AI workspace
Windsurf in November 2026Shipped as Devin Desktop since June 2, 2026. Devin Local is the agent that calls MCP tools; Cascade was removed on September 8, 2026
Sign-inHubSpot is approved once inside Ryze AI on HubSpot's own screen, with no token to paste. Windsurf then signs in to Ryze AI through browser OAuth and registers itself, so no client ID is pasted
HubSpot tools5 in total: 3 read (listObjects, search, read), 1 write, 1 delete
Can it change HubSpotYes. The write tool creates and updates records and blog posts, and a separate delete tool archives them. Devin Local asks before each MCP tool call by default
Other data in the same chatThe connector address is shared, so other connected platforms appear next to the HubSpot tools. This guide covers the 5 HubSpot tools only
Windsurf plan neededCognition's MCP pages name none and the Devin pricing page has no MCP row. The admin MCP settings carry the label Teams & Enterprise
Ryze AI pricePaid Ads at $89 per month after a 7-day free trial. Adding the connector costs nothing
HubSpot's own option for WindsurfHubSpot's remote MCP server at https://mcp.hubspot.com needs a client ID and secret made in HubSpot. HubSpot's pages name Claude, ChatGPT and Gemini as clients, not Windsurf
HubSpot access of the connectionContacts, companies, deals, owners, lists and CMS content. Tickets and custom objects are not covered
Last testedHubSpot calls on November 14, 2026 through the connector. No step inside Windsurf was run

Windsurf was renamed Devin Desktop on June 2, 2026; Cognition's changelog, its rename post and its FAQ all give that date. The MCP documentation moved to Devin's site: docs.windsurf.com/windsurf/cascade/mcp redirects to docs.devin.ai, and windsurf.com redirects to devin.ai/desktop, titled Devin Desktop. This guide keeps the name Windsurf because that is what people search for, and takes menu names and file paths from the current Devin docs. Cascade conversations can no longer be started, so an older step that opens a Cascade MCP panel is out of date. If your install looks different, check which Customize page it shows.

Before you start

  • Windsurf (Devin Desktop) on Mac, Windows or Linux. Cognition's MCP documentation names no plan for adding a server. The Devin Local page says Enterprise admins manage MCP registries under MCP & ACP in team settings, and the admin reference lists the MCP allowlist under Teams & Enterprise, so on a team account an admin may need to approve the Ryze AI server first.
  • A HubSpot user who can install apps. HubSpot lets a Super Admin or a user with App Marketplace access install an app. Any other user needs a Super Admin to do the install. Each connection is one HubSpot portal, and you choose the portal during the sign-in.
  • A Ryze AI workspace on a 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 covers publishing Content Plan articles to a HubSpot blog. Adding the connector is free, but the HubSpot tools need an active plan or trial.

How to connect Windsurf to HubSpot

Two steps happen in Ryze AI and HubSpot, three in Windsurf, and the last is your first prompt. The connector URL is the same for every user.

  1. Connect your HubSpot portal in Ryze AI

    Create a Ryze AI account or sign in, open Integrations and click Connect on the HubSpot card. Sign in to HubSpot, choose the portal and click Choose Account.

  2. Approve the permissions in HubSpot

    Approve the requested permissions. HubSpot sends you back to Ryze AI with the connection saved, and no private app token is pasted anywhere.

  3. Open the MCP settings in Windsurf

    From the Agents window open the Customize page and click MCPs. Use Install MCPs for to pick the scope, for example This computer.

  4. Add the Ryze AI server

    Open the config file and add the server under mcpServers: "ryze": {"url": "https://connector.get-ryze.ai/mcp"}. The user file is ~/.config/devin/mcp_config.json and the project file is .devin/mcp_config.json.

  5. Sign in to the connector

    Refresh the list under This computer. When the ryze server wants authorization it offers an Authenticate button: click it, finish the Ryze AI sign-in in your browser and click Allow connection. In Devin CLI the matching command is devin mcp login ryze.

  6. Ask your first question

    Ask: Search my HubSpot deals created in the last 30 days and show name, amount and stage. Approve the tool call when Windsurf asks.

The Ryze AI HubSpot guide covers the HubSpot side of the connection, and the Ryze AI help article on API keys and the MCP endpoint covers the connector URL.

Sources: Devin Desktop: MCP and customizations, Devin CLI: MCP configuration, Devin Desktop changelog, Ryze AI HubSpot guide, HubSpot: install apps from the Marketplace. Checked November 14, 2026.

Config file, Devin CLI and imports

Windsurf now runs on Devin, so the same server can be added in the editor settings, in a config file or from the Devin CLI. Pick the route that matches how you work.

Devin Desktop (Windsurf) config file

{ "mcpServers": { "ryze": { "url": "https://connector.get-ryze.ai/mcp" } } }

Use ~/.config/devin/mcp_config.json when you want Ryze AI in every project, or .devin/mcp_config.json to keep it with one repository. The project file travels with the repository, so everyone who clones it sees the entry; Devin also reads a gitignored .devin/mcp_config.local.json for an entry meant for you alone. Devin Local supports stdio, Streamable HTTP and SSE with OAuth for each, trying Streamable HTTP first and falling back to SSE on 4xx errors that are not about sign-in.

Devin CLI

devin mcp add -s user ryze https://connector.get-ryze.ai/mcp devin mcp login ryze

The first command writes the server to your user config. The second opens the Ryze AI sign-in, where you click Allow connection. Use them when you would rather not edit JSON by hand. Without -s user the entry goes to the gitignored local file of the folder you are in.

Servers kept in an old Windsurf file

Cognition's import page says Devin CLI reads MCP servers from the old Windsurf file ~/.codeium/<channel>/mcp_config.json (the stable channel uses ~/.codeium/windsurf/), so for the CLI an entry there needs no second copy. That page is written for the CLI. For Devin Desktop the FAQ says only that Windsurf settings carry over to Devin Local, so check the This computer list before adding ryze again. Older Ryze AI pages show the key serverUrl for Windsurf. Whether serverUrl still works was not verified; the current Devin reference lists url, so this guide uses url.

Sign-in and limits

OAuth uses dynamic client registration by default, so there is no client ID or secret to enter for the Ryze AI connector. Each MCP client keeps its own OAuth session, so a Ryze AI sign-in made in another tool does not carry over to Windsurf. The Devin Local page describes the Needs authentication state for expired credentials only. For a first sign-in, the July 29, 2026 release note added an Authenticate button for servers that need authorization, and the Devin CLI page says an OAuth server asks for a sign-in the first time it is used. Since November 8, 2026 the "..." menu in a session header can also re-authenticate a server.

Windsurf and MCP: the facts in one table

TopicWhat Cognition's documentation says
Where you add a serverThe MCPs tab of the Customize page in the Agents window, with Install MCPs for set to a scope such as This computer. Its Available list installs servers from MCP registries
Config filesUser: ~/.config/devin/mcp_config.json, or %APPDATA%\devin\mcp_config.json on Windows. Project: .devin/mcp_config.json. Private override in a project: .devin/mcp_config.local.json, ignored by git
A remote entryurl is the one required field. transport, headers, oauthClientId, oauthClientSecret, oauthResource, oauthScopes, disabled and disabledTools are optional
Transportsstdio, Streamable HTTP and SSE. A url goes over Streamable HTTP first; SSE is tried on the same address only after a 4xx that is not about sign-in
Sign-inOAuth with dynamic client registration. A 401 carrying a WWW-Authenticate challenge counts as a request to sign in, and the server URL travels as the OAuth resource
Static keysA token for a remote server goes in headers. ${env:VAR} and ${file:/path} keep the secret itself out of the file
Tool namesmcp__<server>__<tool>. By that pattern the HubSpot search tool would be mcp__ryze__hubspot__search; this guide did not see the name in Windsurf
ApprovalDevin Local asks before every MCP tool call. A grant covers one tool or the whole server, for the session or for good
Rules and modesAllow, Deny and Ask rules in Devin Local settings take patterns such as mcp__ryze__*, and deny wins. Bypass Permissions mode skips the prompts unless the organization requires approval
Where servers are managedThe This computer list (switch on or off, open the config file, refresh) and, since November 8, 2026, the "..." menu of a session header. Each server logs to its own MCP: <server> channel
Admin controlsAllow MCP, MCP allowlist, MCP registry and MCP registry URLs, labeled Teams & Enterprise. One allowlisted server shuts out every other one
PlanPlans are Free, Pro, Max, Teams and Enterprise. None is named for adding an MCP server
JetBrains pluginWindsurf Plugins for JetBrains add servers under Settings > Tools > Windsurf Settings > Add Server. Cognition says that plugin is in maintenance mode

Sources: Devin Desktop: MCP and customizations, Devin CLI: MCP configuration, Devin CLI: MCP overview, Devin CLI: config file, Devin CLI: read config from other tools, Devin Local permissions, Devin Local modes, Devin Desktop admin controls, Devin Desktop usage and plans, Devin Desktop FAQ, Windsurf Plugins MCP page. Checked November 14, 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

Run claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp --scope user, then /mcp inside Claude Code to sign in.

Claude on the web and Desktop

Open Customize, Connectors, click + Add, choose Add custom connector, name it Ryze AI and enter the URL. In Claude you can set write and delete tools to Needs approval under Customize > Connectors > Ryze AI > Tool permissions.

ChatGPT

Add the same URL as an app under Settings > Apps, pick the workspaces and start a new chat. If the connector was added before HubSpot was connected in Ryze AI, remove and re-add it so the tool list refreshes.

Cursor

Add the server to ~/.cursor/mcp.json or .cursor/mcp.json.

{ "mcpServers": { "ryze": { "url": "https://connector.get-ryze.ai/mcp" } } }

HubSpot access and Windsurf settings

Two sign-ins are involved: HubSpot for CRM access and Ryze AI for the connector. Three things decide what the Windsurf agent can reach.

Which portal
The portal you chose when connecting HubSpot in Ryze AI. One connection is one portal. You can connect several portals to one workspace; the primary one is used unless you name another, and the tools take an optional connection_id.
Which permissions HubSpot granted
The access token carries the scopes the Ryze AI app asked for, not your own record permissions. HubSpot's own example: a user who can view only owned contacts, but authorizes the contacts read scope, gives the app a token that can view every contact in the account.
What Windsurf asks first
Devin Local asks before each MCP tool call by default, so an update to a deal waits for your click until you grant the tool or the whole server.

Access behind each action

What each HubSpot tool can do depends on the scopes granted at install. The table maps each action Ryze AI documents to the HubSpot area behind it.

Action in Ryze AIHubSpot area behind it
Read and edit contacts, companies and dealsRead and write scopes for each of the three objects
Search records with filtersThe CRM Search API, through the read scopes of the object searched
Look up account ownersOwners read
Read property definitionsContact schema read and deal schema read; deal schema write is also requested
Read contact listsLists read. Lists are not edited
Read and edit blog postsThe content scope, which HubSpot offers to CMS Hub Professional or Enterprise and Marketing Hub Professional or Enterprise accounts only

The HubSpot scopes of the default connection

Windsurf itself holds only a Ryze AI sign-in. The HubSpot access stays with the Ryze AI app, which asks for the scopes below. The names are HubSpot's; the right-hand text is what HubSpot says each one covers, and the last column says how Ryze AI uses it.

HubSpot scopeWhat HubSpot says it coversWith Ryze AI
crm.objects.contacts.read, crm.objects.contacts.writeView properties and details about contacts; create, delete and change contactsRequired. Read and edit
crm.objects.companies.read, crm.objects.companies.writeView properties and details about companies; create, delete and change companiesRequired. Read and edit
crm.objects.deals.read, crm.objects.deals.writeView properties and details about deals; create, delete and change dealsRequired. Read and edit
crm.objects.owners.readView details about the users assigned to a CRM recordRequired. Read only
crm.schemas.contacts.readView property settings for contactsRequired. Read only
crm.schemas.deals.read, crm.schemas.deals.writeView, create, delete or change property settings for dealsRequired
crm.lists.readView details about contact listsRequired. Read only
contentContent APIs, including website pages, landing pages and blog APIs. CMS Hub or Marketing Hub Professional or Enterprise onlyRequired. Blog posts, read and edit
files, cms.functions.read and write, knowledge base, membership access groupsFiles, serverless functions, knowledge base articles and membership groups, each on the HubSpot tiers that have themOptional. HubSpot drops an optional scope when the chosen account has no access to that tool

Not on the list: custom object scopes, list editing, ticket scopes and the Sensitive Data scopes. In the test a ticket search through the default connection was refused with status not_allowed. Custom objects, list edits and tickets therefore stay outside this connection, and Ryze AI documents no scope for company property settings either.

Sources: HubSpot: scopes, HubSpot: working with OAuth, HubSpot: install apps from the Marketplace, Ryze AI HubSpot guide. Checked November 14, 2026.

Removing access

Inside Windsurf you have four options: turn the ryze toggle off under Customize > MCPs, add "disabled": true to the entry so its tools disappear, delete the entry from mcp_config.json, or run devin mcp remove ryze. Running devin mcp logout ryze forgets the saved sign-in and keeps the server. To end HubSpot access as well, click View on the HubSpot card in Ryze AI and use Disconnect for the portal. HubSpot's own route is Settings, Integrations, Connected Apps, Actions, Uninstall.

What Windsurf can do in HubSpot

The Ryze AI connector exposes 5 HubSpot tools: 3 read, 1 write and 1 delete. Writes and deletes are separate tools, so you can approve them separately. By Cognition's naming pattern, Devin shows each one as mcp__ryze__ followed by the name below. Every tool takes a workspace argument and an optional connection_id for a specific portal.

ToolTypeWhat it does
hubspot__listObjectsReadLists CRM records of one object type page by page, with the properties you choose and the IDs of associated records. The page size goes up to 100.
hubspot__searchReadSearches records through the HubSpot CRM Search API with filter groups, sorts, a text query and chosen properties. Filter groups are joined with OR and the filters inside a group with AND.
hubspot__readReadSends a GET request to a HubSpot JSON API path, such as a record, property definitions, owners, a list or blog posts. The path takes up to 2,048 characters.
hubspot__writeWriteCreates or updates a HubSpot resource, such as a contact, company, deal or blog post, and adds associations between records.
hubspot__deleteDeleteDeletes (archives) a HubSpot resource by ID, such as a CRM record or blog post. Most CRM deletes go to HubSpot's recycling bin.

Approvals in Windsurf

Devin Desktop asks before calling any MCP tool by default, so a search and an update both prompt until you change that. Loosening it for the ryze server also removes the prompt in front of the write and delete tools, so allow only what you need. Scheduled tasks in Ryze AI run without an approval step, and the Ryze AI chat has its own Tool approvals setting that starts on Skip all approvals; Approve write & delete and Manual approve are the stricter choices.

To keep the delete tool out of reach, add a Deny rule for mcp__ryze__hubspot__delete in Devin Local settings, or list hubspot__delete under disabledTools in the ryze entry. Both follow Cognition's documentation and were not tried in Windsurf.

Limits in numbers

LimitNumber
Burst limit for Marketplace OAuth apps110 requests every 10 seconds for each HubSpot account that installs the app, not counting the CRM Search API. Whether this is the figure for the Ryze AI app was not confirmed, and no response in the test carried a rate limit header.
CRM search rate5 requests per second per account. Search responses carry none of the rate limit headers.
Search page size10 records by default, 200 at most. A search with limit 201 was refused in the test.
Search result cap10,000 results for one query. Paging past it returns a 400 error.
Search filtersAt most 5 filter groups with up to 6 filters each, 18 filters in all.
Search query length3,000 characters at most.
Search delayA new or changed record can take a few moments to appear in search. Archived records never appear.
List and batch sizeUp to 100 contacts in one list request, and batch operations take 100 records at a time.
Access token life30 minutes. The app refreshes it with its refresh token.
After the limitHubSpot answers 429. The daily limit resets at midnight in the account's time zone.
Deleted recordsHubSpot restores deleted records for up to 90 days. Permanent and GDPR deletions skip the bin.
Blog posts API20 results per page by default.

Every client sees the same limits. CMS source-code file endpoints return raw files and fail through the read tool, and a deleted blog post may not be recoverable. HubSpot returns a default subset of properties unless you name fields, so ask for the ones you want. Cognition's pages read on November 14, 2026 give no cap on the number of MCP servers or tools in Devin Local.

Sources: HubSpot: usage guidelines, HubSpot: search the CRM, HubSpot: contacts guide, HubSpot: manage OAuth tokens, HubSpot: restore deleted records, HubSpot: blog posts guide. Checked November 14, 2026.

What the default connection can read, tested

These are the calls behind this guide, sent on November 14, 2026 to a HubSpot portal connected in Ryze AI through the default connection. They came from Claude Code, a different MCP client on the same connector that Windsurf uses. All 11 were read-only, and no record content is kept on this page.

What was askedWhat came backOutcome
Contacts whose email equals a random 20-letter stringAn empty result, {"total":0,"results":[]}Worked
Companies whose domain equals a random stringThe same empty shapeWorked
Deals whose name equals a random stringThe same empty shapeWorked
One contact, listing with limit 1 and one chosen propertyOne result with id, properties, createdAt, updatedAt, archived and url, plus a paging block with after and link. HubSpot added createdate and lastmodifieddateWorked
Contacts filtered on a property that does not existError 400, "There was a problem with the request."Refused
Contacts with limit 201Error 400 VALIDATION_ERROR, limit must be in range [0..200]Refused
Tickets with a filter that cannot matchStatus not_allowedRefused
A deal with ID 0Status not_foundNot found
A contact with an 18-digit ID that does not existStatus not_found, HubSpot answered with an HTML 404 pageNot found
Blog posts with two made-up IDsStatus not_found with the same HTML 404 pageNot found

The last two rows do not show whether blog reads work on a given portal, because the IDs did not exist. The write and delete tools were not run, because they change the portal. No record was read by ID, and owners, property definitions and lists were not read.

First 3 prompts to run

Answers come from your own portal, so each prompt says what comes back and shows no sample numbers. Replace the placeholders with your own values.

1. Find a contact by email

Search my HubSpot contacts for the email address person@example.com and show first name, last name, lifecycle stage and create date.

Tools used: hubspot__search

What comes back: A list of matching contacts with the properties you named, or an empty result when nobody matches. Nothing is changed.

2. List recent deals

Search my HubSpot deals created in the last 30 days and show deal name, amount, close date and stage.

Tools used: hubspot__search

What comes back: The deals that match, with the properties you asked for. HubSpot returns a fixed default set unless properties are named, so the prompt names them.

3. Create a deal and link it

Create a deal named Test renewal in my default pipeline and associate it with the company with domain example.com.

Tools used: hubspot__search, hubspot__write

What comes back: A search for the company, then one create call with the association once you approve the tool call in Windsurf. This changes the portal, so check the result in HubSpot.

The first two prompts match the kind of search that ran on November 14, 2026, with different filters. The third changes data and was not run, so this page describes what comes back and shows no result for it. Keep Windsurf's approval prompt on for the ryze server while you try it.

10 jobs to hand to the Windsurf agent

Ten jobs to give the Devin Local agent, each tied to the tool it would use. Searches and listing were run in the test, and the others rest on the tool descriptions. A job that changes something waits for your click in Windsurf unless you allowed the tool.

JobAsk the agentToolWorks on the default connection
Contact lookupFind the contact with this email and show the properties I name.hubspot__searchYes
Recent dealsList deals created in the last 30 days with name, amount and stage.hubspot__searchYes
Stale deals with ownersFind open deals with no change in 30 days and show the owner of each.hubspot__search, then hubspot__read on crm/v3/ownersYes. The owners read was not run in the test
Company with its peopleFind the company with this domain and list its associated contacts and deals.hubspot__search, then hubspot__listObjectsYes. Associations were not requested in the test
Page through contactsList contacts page by page with lifecycle stage and create date.hubspot__listObjectsYes
Property checkShow which contact and deal properties exist before you build a filter.hubspot__read on crm/v3/properties/contactsYes. Not run in the test
Read a listRead the contact list with this ID and its details.hubspot__read on crm/v3/lists/{listId}Yes, read only. Adding members is not supported
Create a dealCreate a deal and associate it with this company and contact.hubspot__writeYes, after you approve the call in Windsurf
Update a propertySet this property on the contact, company or deal with this ID.hubspot__writeYes, after you approve the call in Windsurf
Search ticketsFind open tickets for this company.hubspot__searchNo. The ticket search was refused with not_allowed

6 ways to connect Windsurf to HubSpot

Six ways reach HubSpot from Windsurf. This guide uses the first one, the Ryze AI connector, as the main way: Devin Desktop needs one url entry, HubSpot is approved on its own screen inside Ryze AI, and you create no HubSpot app or token. Of the other five, only HubSpot's skills repository and Zapier's client list name Windsurf. For the rest the setup cell describes the route in Devin's file format, because the vendor pages give no Windsurf steps. None of the six was run in Windsurf.

WayRuns whereSetup in WindsurfWhat it reaches in HubSpotPrice
Ryze AI connector (the main way)Hosted. One address for every userA url entry in mcp_config.json, or devin mcp add, then Authenticate. Sign-in in the browserContacts, companies and deals, to read and edit. Owners, property definitions and lists, to read. Blog posts, to read and edit on portals with the content scope. Deletes go through a separate toolPaid Ads is $89 per month with a 7-day free trial
HubSpot remote MCP serverHosted by HubSpot at https://mcp.hubspot.comCreate an MCP connector in HubSpot under Development, MCP Connectors for a client ID and secret, then point a client that supports OAuth with PKCE at the address. Devin's entry has oauthClientId and oauthClientSecret fields. How the redirect URL works in Devin was not checked36 tools in the documented list, covering CRM records, segments, custom objects, pipelines, content, campaigns and more. HubSpot's list has no delete tool. Generally available since April 13, 2026No price stated. HubSpot calls it available to all accounts
HubSpot Agent CLI (beta)On your computer, a single binaryInstall the binary, run hubspot auth login, then npx skills add hubspot/agent-cli-skills. The skills repository README names Claude Code, Cursor and Windsurf. The agent runs commands in a terminal, with no MCP entryRead and write on records with your own permissions: contacts, companies, deals, tickets, custom objects, workflows, pipelines and more. Some metadata and destructive operations need a service key during the betaNo price stated. Under HubSpot's Developer Beta Terms
Zapier MCPHostedZapier lists Windsurf among its other clients, and says clients without their own setup page use a connection token. Zapier turns on actions for apps already connected to your Zapier accountThe HubSpot actions you enable in Zapier, such as create contact, create company, add contact to list and create associationsNo separate MCP price. Each successful tool call uses 2 tasks from your Zapier plan
ComposioHostedA url entry for https://connect.composio.dev/mcp, then authorize HubSpot on first use. Composio's pages name Claude, Cursor and ChatGPT, not Windsurf354 HubSpot tools and 2 triggers, read and write, including batch create, update and archiveFree plan: 10,000 tool calls a month. Standard is $18 per seat per month
baryhuang/mcp-hubspot, open sourceA Docker container you runA command entry in mcp_config.json that runs docker with a HubSpot access token you create. Needs the contacts and companies scopes and the sales email read scope7 tools for contacts, companies, activity and conversations. The README lists no deals toolsFree, MIT licence. 129 GitHub stars, last push November 11, 2025

Three HubSpot options that do not fit this job

  • HubSpot's connectors for ChatGPT, Claude, Gemini and Microsoft Copilot. HubSpot's marketing page says they are live. They run inside those assistants. HubSpot names no connector for Windsurf.
  • HubSpot's Developer MCP server. HubSpot lists Windsurf as a supported client, and hs mcp setup installs it. It is built for making HubSpot apps and CMS assets, with 23 tools for documentation, projects and deploys, and it does not reach CRM records.
  • The older @hubspot/mcp-server package and reporting connectors. The package has not had a release since June 18, 2025 and needs a private app token. HubSpot said creation of legacy private apps would be disabled from September 28, 2026 for accounts created on or after that date and from October 26, 2026 for older ones. Windsor.ai and Coupler.io give reporting access, and Coupler.io says it hands the AI aggregated data, not individual records. Neither page names Windsurf.

Which one to pick

Ryze AI is the best way to connect Windsurf to HubSpot for searching and editing contacts, companies and deals, with one caveat: tickets, custom objects and list edits are outside the connection, and HubSpot's own 36-tool server reaches more of the account. Choose HubSpot's remote server when you need those areas and can create an MCP connector in HubSpot and test its redirect URL in Devin. Add the Developer MCP server when the agent is building a HubSpot app, since Devin reads several named servers from one config file and leaves ryze in place. Composio and Zapier make sense when your team already uses one of them for other apps. The open-source server suits you when you want a few contact and company tools and can run Docker.

Sources: HubSpot: remote MCP server setup, HubSpot: remote MCP server changelog, HubSpot: AI tools, HubSpot: Agent CLI, HubSpot: agent-cli-skills, HubSpot: Developer MCP server, @hubspot/mcp-server on npm, HubSpot: legacy private app sunset, Zapier MCP for HubSpot, Zapier MCP quickstart, Composio HubSpot toolkit, Composio pricing, baryhuang/mcp-hubspot, Windsor.ai MCP, Coupler.io MCP for HubSpot, Devin CLI: MCP configuration. Checked November 14, 2026.

Windsurf, HubSpot and MCP: dates that matter

DateWhat happened
February 13, 2025Windsurf Wave 3 brought MCP servers to Cascade, on individual plans first (Cognition launch post).
July 17, 2025Windsurf 1.11.0 added the Streamable HTTP transport and MCP authentication in place of access tokens or API keys in the config.
September 1, 2025HubSpot opened the remote HubSpot MCP server as a public beta.
February 19, 2026HubSpot's Developer MCP server became generally available.
April 13, 2026The remote HubSpot MCP server became generally available to all HubSpot accounts, with write access added and OAuth 2.1 with PKCE required.
June 2, 2026Windsurf became Devin Desktop (v3.0.12).
July 29, 2026Devin Desktop 3.6.22 gave servers that need authorization an Authenticate button.
August 27, 2026HubSpot announced that creating legacy private apps would be disabled, with existing private apps left working and Service Keys as the replacement.
September 8, 2026Devin Desktop 3.9.19 removed Cascade, leaving Devin Local as the only built-in agent.
September 15, 2026HubSpot announced the end of support for API versions v1 to v3, with enforcement in September 2027, and for v4 on March 30, 2027. Its Fall 2026 Spotlight post added custom objects, Leads and more to its own server and Claude connector.
November 8, 2026Devin Desktop 3.12.32 put each session's MCP servers in the "..." menu of the session header.
December 4, 2026HubSpot's Pipelines API V1 stops responding after this date.

Sources: Devin Desktop changelog, Cognition: Windsurf Wave 3, Cognition: Windsurf is now Devin Desktop, HubSpot: remote MCP server beta, HubSpot: remote MCP server generally available, HubSpot: Developer MCP server GA, HubSpot: legacy private app sunset, HubSpot: legacy APIs and apps, HubSpot: Fall 2026 Spotlight, HubSpot: Pipelines API V1 sunset. Checked November 14, 2026.

How this guide was tested

Two kinds of checks stand behind this guide: the connector's tool list and HubSpot calls through the connector, both on November 14, 2026. Each row names what was run and what came back.

What was runWhat came back
The tool list from the connectorThe five HubSpot tool names loaded by name, each with a definition that matches the tools table above.
Object types in the tool definitionsContacts, companies and deals.
6 searches through the default connectionThree valid empty results for contacts, companies and deals, and three refusals: a missing property, a limit of 201 and a ticket search.
One list call on contactsOne result and a paging block, as in the table of tested reads.
4 reads by pathAll four returned not_found, for IDs that do not exist. The messages are in the errors table below.
Limits seen in a responseThe search limit range, 0 to 200. No rate limit or quota header reached the tool output.

Not run for this guide: any step inside Windsurf. Neither Devin Desktop nor Devin CLI was opened, so the mcp_config.json entry, the Authenticate button, devin mcp add, devin mcp login and the approval card are described from Cognition's documentation as it read on November 14, 2026. The signed-in client for the calls was Claude Code, which reaches the same server and the same five tools. The write and delete tools were not run, because they change the portal, and no existing record or blog post was read.

Windsurf and HubSpot errors and fixes

Exact error messages from the test

These are the exact messages HubSpot and the connector returned in the test on November 14, 2026. If the Devin Local agent shows one of them, the row says what went wrong and what to ask next.

MessageWhat it meansWhat to do in Windsurf
limit must be in range [0..200] (actual value: 201)The CRM search returns at most 200 records per page. HubSpot labelled it VALIDATION_ERROR.Ask for 200 or fewer per page and page on with the after value.
There was a problem with the request.HubSpot rejected the search body and did not say which property was wrong. In the test the filter named a property that does not exist.Ask the agent to read the property definitions for the object first and use the internal property 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 through Ryze AI. For tickets use HubSpot's own connector or its remote MCP server.
Object not found. objectId is usually positive.Status not_found. No record has that ID.Ask the agent to search for the record first and use the id that comes back.
[hubspot] GET crm/v3/objects/contacts/<id>: provider returned text/html;charset=iso-8859-1 (status 404) "Error 404 Not Found"HubSpot answered with an HTML 404 page, and the read tool, which parses JSON, reported it. The same form came back for blog post paths.Check the ID. Search for the contact by email instead, or list blog posts and take an ID from the list.

Other problems

The server shows Needs authentication
Click Authenticate in the MCPs list to run the browser authorization again. In Devin CLI, run devin mcp logout ryze and then devin mcp login ryze, and click Allow connection.
Nothing happens after adding the server
Refresh the MCP list in Customize, MCPs. Check that the entry sits under mcpServers and the JSON is valid. Running devin mcp list shows what the CLI reads.
The server works in one project only
A .devin/mcp_config.json entry applies to that repository. Put the server in ~/.config/devin/mcp_config.json for every project.
The server stays disconnected on a team account
When an admin keeps an MCP allowlist, every server outside it fails to connect and its tools are missing. Ask the admin to add the Ryze AI server to the allowlist.
The agent is off in this folder
A workspace opened in Restricted Mode has Devin Local and every ACP agent disabled, so the Ryze AI tools cannot run there.
The HubSpot tools do not appear
If HubSpot was connected in Ryze AI after the server was added, remove the ryze entry and add it again, then start a new session so the tool list refreshes.
HubSpot will not let you approve the install
Installing an app needs a Super Admin or a user with App Marketplace access. Ask one of them to connect the portal in Ryze AI.
A blog post cannot be read or edited
Blog access needs the content scope, which HubSpot offers to CMS Hub or Marketing Hub Professional or Enterprise accounts. Without that scope the post tools have no access to it.
A property comes back empty or is missing
HubSpot returns a default subset of properties unless you name fields. Ask for the properties you want by their internal names.
A new record is not in the search yet
HubSpot says a new or changed record can take a few moments to appear in search. Ask again, or read the record by ID.
A deleted record is gone
Most CRM deletes go to HubSpot's recycling bin, where records can be restored for up to 90 days. A deleted blog post may not be recoverable.
The agent reports that a subscription is required
The HubSpot tools run only on an active Ryze AI plan or free trial. Start the trial in Ryze AI, then retry.

Terms on this page

Devin Local
The agent inside Windsurf (Devin Desktop) that calls MCP tools. It took over from Cascade.
mcp_config.json
Devin's MCP file. Each server is a named entry under mcpServers; this guide names the entry ryze.
Portal
HubSpot's word for one account. Each Ryze AI connection is one portal.
Scope
A permission an app asks for at install time. Each scope opens a set of HubSpot API endpoints and the data behind them.
Filter group
A block of filters in a CRM search. Filters inside a group are joined with AND, groups with OR; at most 5 groups of 6 filters.
Recycling bin
Where deleted CRM records go. They can be restored for up to 90 days.
Segment (list)
HubSpot's current name for a contact list. The Lists API is now the Segments (Lists) API.

Sources: Devin Local overview, HubSpot: scopes, HubSpot: search the CRM, HubSpot: lists guide, Model Context Protocol. Checked November 14, 2026.

Frequently asked questions

How do I connect Windsurf to HubSpot?

Connect your portal in Ryze AI under Integrations by signing in to HubSpot and approving the permissions. Then add "ryze": {"url": "https://connector.get-ryze.ai/mcp"} to mcp_config.json, or run devin mcp add, and sign in with Authenticate or devin mcp login ryze.

Is there a HubSpot MCP server for Windsurf?

Yes. The Ryze AI connector at https://connector.get-ryze.ai/mcp has 5 HubSpot tools. HubSpot also runs a remote MCP server at https://mcp.hubspot.com, and its Developer MCP server lists Windsurf as a client but does not reach CRM records. Zapier, Composio and an open-source server are further options.

What is the HubSpot MCP server URL for Windsurf?

For the Ryze AI connector the address is https://connector.get-ryze.ai/mcp, the same for every user. HubSpot's own remote server is https://mcp.hubspot.com and needs a client ID and secret from an MCP connector you create in HubSpot. HubSpot's Developer MCP server has no address: it runs on your computer.

Does HubSpot have an official MCP server?

Yes, two. The remote server at https://mcp.hubspot.com was generally available on April 13, 2026 and has 36 tools in its documented list. The Developer MCP server runs locally for building apps and CMS assets. HubSpot also offers connectors for ChatGPT, Claude, Gemini and Microsoft Copilot.

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

Ryze AI is the best way to connect Windsurf to HubSpot for searching and editing contacts, companies and deals, with one caveat: tickets and custom objects are outside the connection. HubSpot's remote server reaches more of the account but needs a connector made in HubSpot, and its pages do not name Windsurf as a client.

Can Windsurf edit my HubSpot contacts and deals?

Yes. Through Ryze AI the write tool creates and updates contacts, companies, deals and blog posts and adds associations between records. Devin Local asks before each MCP tool call by default, so you can review each change.

Can Windsurf delete HubSpot records?

Only through the separate hubspot__delete tool, which archives a record or blog post by ID. Most CRM deletes go to HubSpot's recycling bin for up to 90 days. You can add a Deny rule for the tool in Devin Local settings or list it under disabledTools.

Can Windsurf read HubSpot tickets or custom objects?

Not through the default Ryze AI connection. A ticket search was refused with status not_allowed in the test, and the requested scopes do not include custom objects. HubSpot's remote MCP server and Agent CLI list both areas.

Which Windsurf plan do I need?

Cognition's MCP pages name none, and the Devin pricing page has no MCP row. On Teams and Enterprise an admin may keep an MCP allowlist, which would block a server outside it.

Do I need a HubSpot private app or token?

No. The Ryze AI connection uses HubSpot's OAuth screen, so you sign in, choose the portal and approve the permissions. HubSpot has also announced that legacy private app creation is being disabled.

Is HubSpot's remote MCP server supported in Windsurf?

Not by name. HubSpot's setup page says any MCP client that supports OAuth with PKCE can connect and names Claude, ChatGPT and Gemini as clients. Devin's config has oauthClientId and oauthClientSecret fields, so a connection looks possible, but it was not run.

Can I connect more than one HubSpot portal?

Yes. Several portals can be connected to one Ryze AI workspace, one is the primary and is used unless you name another, and the tools accept an optional connection_id. Each connection is one portal.

Why do the HubSpot tools not show up in Windsurf?

If you connected HubSpot in Ryze AI after adding the server, remove the ryze entry, add it again and start a new session so the tool list refreshes. Also check the MCP allowlist if your team keeps one.

How much does it cost to connect Windsurf to HubSpot?

Adding the connector costs nothing, 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, Agency is $279 per month and Shopify CRO is $1,499 per month. Annual billing takes 30% off the first year.

How do I disconnect HubSpot from Windsurf?

Turn the ryze server off under Customize > MCPs, delete its entry, or run devin mcp remove ryze. To end HubSpot access, use Disconnect on the HubSpot card in Ryze AI.

Sources

HubSpot pages checked November 14, 2026; Windsurf and Devin pages checked November 14, 2026.

Connect HubSpot to Windsurf

Your portal connects once in Ryze AI, then Windsurf reads and edits contacts, companies, deals and blog posts through 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.