MCP server
The MCP server lets an AI assistant a person connects search a product's help, ask questions, start code investigations, contact the team and read past conversations. A team address reaches every product on the team after a sign-in, and each product's own address gives anyone its public help.
On this page
Which address to use
Every product on a team is reached through the team address, https://mcp.heycactus.ai/mcp. Every tool on it needs a sign-in, and a call names its product when the team has more than one.
Each product also has its own address, https://mcp.heycactus.ai/p/<slug>/mcp, where <slug> is the name its help site answers to. Anyone can use the public tools there, and the team's tools need a sign-in.
What each tool does
Each tool is offered on one address, on both, or only to a caller who can run it.
Tool | What it does | Team address | Product address |
|---|---|---|---|
| What it does Finds published help pages by words | Team address Needs | Product address Anyone |
| What it does Reads one help page in full | Team address Needs | Product address Anyone |
| What it does Lists the help's sections and how many pages each holds | Team address Needs | Product address Anyone |
| What it does Reads the dated record of releases behind What's new | Team address Needs | Product address Anyone |
| What it does Search, then read one result in full: pages for anyone, and past conversations too for a signed-in teammate | Team address Needs | Product address Anyone, pages only |
| What it does Find and read past conversations | Team address Needs | Product address Needs |
| What it does Answers from everything the team can see, and keeps the answer as a conversation | Team address Needs | Product address Needs |
| What it does Answers the way the help site answers a visitor | Team address Not offered | Product address Anyone |
| What it does Start a check of the product's code and read its finding | Team address
| Product address
|
| What it does Sends a message to the team as a conversation | Team address Not offered | Product address Anyone |
| What it does Lists the team's products | Team address Needs | Product address Needs |
contact_team takes the person's email address, where the team's reply goes, and a message of up to 2,000 characters. How the team answers it is on Handoffs.
The setup tools are on the team address only, and they are covered under Setting Cactus up from an AI client below.
Who can call a tool
Sign-in and scopes
A call with no token gets a sign-in prompt when the tool needs one. A call with a token that lacks the tool's scope is refused, and the prompt asks for a new sign-in that allows the scope.
A connection that names no scope is given all three scopes, and a product address's connection is given only read and ask. The scopes mean:
cactus:read: read the team's help pages, what Cactus has learned about the product from its code, and past conversations with customers.cactus:ask: ask questions and start investigations, and each one starts a new conversation.cactus:setup: create products, connect GitHub and choose which repositories Cactus reads.
If you are not on a team yet
A signed-in person who is on no team can call only get_setup. Any other tool is refused with a message that they are not on a Cactus team yet. Joining a team is on Joining a team.
A signed-in member is answered from the team's pages and conversations, and anyone else from the published pages.
Which product a call is about
On a team with one product, a call goes to that product without naming it. On a team with several, a call that names no product is refused with the list of refs, and you pass product with one of them. A team with no product is told to create one first.
Asking and waiting for an answer
ask and ask_help wait up to about 230 seconds for the reply. A finished reply comes back as an answer with its cited pages. A reply that is not finished comes back as still working, with a link to the conversation where it is being written and a resume value. Call again with the same question and that resume value to keep waiting for the same answer. A resume value works only for the person who asked.
The link opens the conversation in the team's inbox for a signed-in member, and for anyone else a shared link to that conversation.
A reply's states run from working, to writing, to an answer, to a failure, or to still working when the wait runs out.
The progress notes read "Working on it…" until the answer's first words arrive, then "Writing the answer…".
start_investigation returns an investigation id as soon as the work is queued, and get_investigation reads its status and, once done, its finding with its sources. When the team has no plan, the call returns that Cactus is paused, and nothing is queued.
How many calls you can make
- A caller with no token may make 60 calls every 5 minutes from one network address.
- A signed-in person may make 600 calls every 5 minutes.
- Contact is capped for anyone without a token: 3 an hour per address for each product, 30 a day per product.
- Across all products, one address may contact the team 10 times an hour, and the platform takes 1,000 contacts a day.
- A visitor with no sign-in may get 10 answers an hour from an AI client, per product. A signed-in teammate of the product's team is not counted.
- A question to
askorask_helpmay be up to 4,000 characters, and a search query up to 500.
Setting Cactus up from an AI client
Setting up from an AI client may not be turned on for every account yet.
When it is off, the team address lists only get_setup. A setup call then gets one line with the browser address to set Cactus up in. When it is on, the setup tools are:
get_setup, which reads where setup stands, withcactus:read.create_product,connect_source,chooseanddisconnect_source, each withcactus:setup.get_build, which reads a build's progress withcactus:read, and can wait up to 50 seconds for it to change.
The steps themselves are on Setting up your first product, and Sources and Builds cover what the setup calls set.
If a call fails
What you see | What it means | What to do |
|---|---|---|
A sign-in prompt | What it means The tool needs a sign-in, or the page is withheld from visitors | What to do Connect again and sign in, from AI clients. |
A message that the token does not carry a scope, and a scope name | What it means The connection lacks the scope the tool needs | What to do Connect again and allow the scope it names. |
"This tool works once they're on a Cactus team, and they aren't on one yet." | What it means The person is signed in but on no team | What to do Call |
"This team has more than one product" and a list of refs | What it means The call named no product on a team with several | What to do Pass |
"This team has no product yet. Create one in Cactus first." | What it means The team has no product | What to do Set one up, from Setting up your first product. |
"Cactus is paused because the team has no plan." | What it means Investigations do not start until the team has a plan | What to do Pick a plan, from Plans and billing. |
"Too many questions to this Help Center right now. Try again in" and a number of seconds | What it means A visitor's answers for the hour are used up | What to do Wait the seconds given. A signed-in teammate is not held to this. |
Too many calls | What it means The call limit for this caller is used up | What to do Wait the seconds given. |
"Still working on it." with a link and a | What it means The wait ran out before the reply was written | What to do Call again with the same question and |
"No page at" a slug "on this Help Center" | What it means The slug is not one the caller can read | What to do Call |
"Cactus could not take the question. Try again in a moment." | What it means The question or contact was not taken | What to do Try again in a moment. |