It’s been a few days since the “search-docs” tool of the HubSpotDev MCP stopped working — it always returns “No documentation found for your query”. Only the “fetch-doc” tool seems to be working. Has anyone experienced the same issue?
Hey @AlbertoZ,
Thanks for flagging this! Before the community digs in, it’d be helpful to gather a few more details to point you in the right direction:
- What troubleshooting steps have you already tried?
- What’s your current setup - are you connecting via the CLI (e.g., Claude Code), VS Code, Gemini, or another tool? The HubSpot Dev MCP can connect to a few different environments, so configuration details could be helpful here!
In the meantime, I’d also like to tag in some of our Top Contributors to see if they have any experience with this!
Hey @SteveHTM, @RubenBurdin, @Josh -- Do you have any suggestions for @AlbertoZ on this?
Looking forward to your response!
Sam, Community Manager
Hey @SamTassey,
I haven’t done any real troubleshooting on my end — the HubSpotDev MCP has just been running persistently at the user level on my machine, and over the last few days the “search-docs” tool specifically stopped working as described above. Only “fetch-doc” seems to be operational at this point.
I’m using the HubSpot MCP exclusively through the Claude Code extension for Cursor. Whenever I ask something HubSpot-related, the MCP kicks in — either automatically or because I explicitly tell Claude Code to use it. Up until a few days ago, the default behavior was to use “search-docs” first, which covered most cases just fine. Now it still tries that tool, but since it fails it falls back to “fetch-doc”. That one does work, but it feels like extra overhead for the agent — sometimes it pulls down documents that are too large, which causes errors and forces it to do partial parsing.
Have you seen any evidence of this issue on your side?
Hello @AlbertoZ,
Thanks for the additional context - that’s really helpful! I haven’t personally seen this exact issue, but given you’re running the MCP through Claude Code in Cursor, it could be worth checking whether there’s been a recent update.
In the meantime, here are a few things worth trying on your end:
- Update the HubSpot CLI to the latest version (8.2.0+):npm install -g @hubspot/cli
- Re-run the MCP setup with hs mcp setup and select your client (Cursor/Claude Code)
- Restart Cursor after setup to apply the changes
In the meantime, also tagging a few of our Top Contributors in case they’ve run into something similar:
Hey @SteveHTM, @evaldas, @Anton -- do you have any suggestions for @AlbertoZ on this?
Thanks in advance!
Best,
Sam, Community Manager
Hmm interesting,
can’t reproduce this.
Tried it with something super simple:
Setup:
- CLI: 7.11.2 (had many CMS dev related issues with 8.x)
- IDE: Cursor 3.1.15
Have you tried reinstalling the CLI or downgrading it to the last 7.x version (7.11.2) by uninstalling it first and then run something like
npm install -g @hubspot/cli@7.11.2
best,
Anton
Wait… I’ve just read the screenshot…
Search-docs didn’t find anything for me as well… only the fetch-docs.
So I’ve kinda reproduced it.
Sorry for the misleading info in the first place
Thanks @SamTassey,
Jumping in with a quick update from the team and a couple of additional troubleshooting steps that would help us narrow things down. We have confirmed it’s not working as expected.
@AlbertoZ @Anton could you please runhs doctor
to see if you are missing scopes on your auth token so we can rule that out?
We’re investigating the issue when the docs pages are too large and it causes errors, but for simpler queries the expectation is that search-docs returns a list of URLs with relevance scores for each url and then fetch-docs is called with that URL. They are meant to be used in tandem so it is strangth to get results from one, but not the other (unless they are stored in the context window).
Do you have any of the docs added directly as markdown that could be referenced when running fetch?
I appreciate your patience and help with getting this resolved.
Hey @Jnix284,
here’s my result of hs doctor
HubSpot CLI install
✓ node v20.19.2 is installed
✓ npm v11.7.0 is installed
! Version 7.11.2 outdated
- Run `npm install -g @hubspot/cli` to upgrade to the latest version 8.4.0
CLI configuration
Config File: /path/to/config.yml
Default Account: GS|Developmentbase [test account] (123456789)
✓ Default account active
! Personal access key is valid, but there are more scopes available to your user that are not included in your key.
- To add the available scopes, run `hs account auth` and re-authenticate your account with a new key that has those scopes. Visit HubSpot to view selected and available scopes for your personal access key. View selected scopes: https://app.hubspot.com/personal-access-key/123456789
I’ve redacted the path as well as the HubID and my default portal is one of my CMS sandbox accounts where I’ve enabled all available scopes.
Happy to share the exact path and HubID privately if required
best,
Anton
Hello @Jnix284,
here’s the outpout of hs doctor:
✔ Diagnostics completeHubSpot CLI install✔ SUCCESS node v20.19.2 is installed✔ SUCCESS npm v10.8.2 is installed✔ SUCCESS HubSpot CLI v8.4.0 up to dateCLI configurationConfig File: /path-to-config.ymlDefault Account: sandbox-account [standard sandbox] ([id])✔ SUCCESS Default account active✔ SUCCESS Personal Access Key is valid. View selected scopes: https://app.hubspot.com/personal-access-key/:idNetwork & API connectivity✔ SUCCESS HubSpot API is reachable✔ SUCCESS npm registry is reachableErrors: 0Warning: 0
As to:
Do you have any of the docs added directly as markdown that could be referenced when running fetch?
no, I don’t have any markdown file for HS docs on my machine.
@SamTassey @Jnix284 any news on this?
Thank you.
Hey @AlbertoZ,
Thanks for checking back in, happy to share an update with you and @Anton on this!
Our engineers have reviewed the hs doctor info provided and they haven’t been able to reproduce the issue. The good news is that the tool is working for other users and is working as expected.
If you’re still experiencing an issue, here is the recommendation from our the product team:
Restart whatever tool you’re running the MCP server in (i.e. Claude Code, Gemini, VS Code). You can also try to re-auth your portals with the CLI and restart and try again.
I hope this helps!
Best,
Sam, Community Manager
thank you for your reply.
I’d like to say that the ‘search-docs’ tool has started working for me again and, to be fair, in general that’s true. After your reply I tested it again and it worked.
However, for reasons that are unclear to me, sometimes the tool still fails as I originally reported. I can’t figure out what it depends on though — whether it’s the project I’m running the MCP in that’s responsible, or something else.
As far as you know, are there specific criteria, situations or conditions under which the MCP works versus when it doesn’t? Do you have any suggestions?
Thank you,
Alberto
Hey @AlbertoZ,
Happy to hear things seem to be working as expected for the most part -- tagging in Anton again and few other folks to see if they have any suggestions here --
Hey @Anton, @MichaelMa, @SteveHTM -- Do you have any suggestions additional suggestions for @AlbertoZ on this?
Thanks in advance!
Sam, Community Manager
Hi @AlbertoZ
Yes, the HubSpot Developers documentation itself is accessible, and the website search is also working. The issue seems to be specifically with the search-docs tool in the HubSpotDev MCP. In my case, search-docs returns “No documentation found for your query”, while fetch-doc continues to work. So it may be an issue with the MCP tool’s documentation search/index rather than the HubSpot documentation itself.
I hope this helps you out. Please mark it as Solution Accepted and Like to help another Community member.
This post was created with the assistance of AI tools
Thanks!