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

search_help

What it does

Finds published help pages by words

Team address

Needs cactus:read

Product address

Anyone

read_page

What it does

Reads one help page in full

Team address

Needs cactus:read

Product address

Anyone

list_topics

What it does

Lists the help's sections and how many pages each holds

Team address

Needs cactus:read

Product address

Anyone

read_timeline

What it does

Reads the dated record of releases behind What's new

Team address

Needs cactus:read

Product address

Anyone

search and fetch

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 cactus:read

Product address

Anyone, pages only

search_conversations and read_conversation

What it does

Find and read past conversations

Team address

Needs cactus:read

Product address

Needs cactus:read

ask

What it does

Answers from everything the team can see, and keeps the answer as a conversation

Team address

Needs cactus:ask

Product address

Needs cactus:ask

ask_help

What it does

Answers the way the help site answers a visitor

Team address

Not offered

Product address

Anyone

start_investigation and get_investigation

What it does

Start a check of the product's code and read its finding

Team address

cactus:ask and cactus:read

Product address

cactus:ask and cactus:read

contact_team

What it does

Sends a message to the team as a conversation

Team address

Not offered

Product address

Anyone

list_products

What it does

Lists the team's products

Team address

Needs cactus:read

Product address

Needs cactus:read, and names only that product

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.

How a question to ask or ask_help moves while it is written

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 ask or ask_help may 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, with cactus:read.
  • create_product, connect_source, choose and disconnect_source, each with cactus:setup.
  • get_build, which reads a build's progress with cactus: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 get_setup, or see Joining a team.

"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 product with one of the refs.

"This team has no product yet. Create one in Cactus first."

What it means

The team has no product

What to do

"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 resume value

What it means

The wait ran out before the reply was written

What to do

Call again with the same question and resume, or open the link.

"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 list_topics or search_help for the slugs that exist.

"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.

Sources

Related pages