MCP server

The MCP server at mcp.heycactus.ai lets AI clients search a product's help, ask it questions and start investigations from inside the client. Your team's address reaches every product on your team once you sign in, and each product also has its own address that anyone can use for its public help.

On this page

Copy the address

Your team's address is https://mcp.heycactus.ai/mcp. It reaches every product on your team, and the person who signs in decides what it shows.

Each product also has its own address, https://mcp.heycactus.ai/p/<name>/mcp. The <name> is the name the product's help site answers to. The owner finds the exact address under AI clients.

The MCP page on the help site gives the steps for each client, such as Cursor: open Cactus, go to AI clients in the top navigation, and press Add to Cursor. To hand the setup to an agent instead, see Connecting from an AI agent.

What each address offers

Address

Who can use it

What it offers

https://mcp.heycactus.ai/mcp (team)

Who can use it

A member of a team, signed in. Anyone else is asked to sign in.

What it offers

The team's 18 tools: list_products, search_help, read_page, list_topics, read_timeline, search_conversations, read_conversation, search, fetch, ask, start_investigation, get_investigation, and the six setup tools.

https://mcp.heycactus.ai/p/<name>/mcp (product)

Who can use it

Anyone. With no sign-in it offers the public tools, and a signed-in member also gets the team tools for that product.

What it offers

The public tools: search_help, read_page, list_topics, read_timeline, ask_help, contact_team, search, and fetch.

On the product address, the product is fixed by the address, so no product needs to be named.

Who can call what

A tool that needs a scope can only be run with a token that carries that scope. A call without one is answered with a sign-in challenge.

| Scope | What an AI client may do with it | | --- | --- | --- | | cactus:read | Read your team's help pages, what Cactus learned from your code, and past conversations with your customers. | | cactus:ask | Ask Cactus questions and start investigations. Each one starts a new conversation. | | cactus:setup | Set up Cactus for your team: create products, connect GitHub and choose which repositories Cactus reads. |

A person on the team address who is not yet on a team is offered get_setup alone, and any other tool they call is refused.

Which product a call is about

On the team address, a team with more than one product must say which one a call is about: the client passes product with the product's ref. list_products returns each product's ref. A team with no product gets a message to create one in Cactus first.

Limits

Caller

Limit

Source

Signed in as a member

Limit

600 calls per 300 seconds

Not signed in

Limit

60 calls per 300 seconds, per caller address

contact_team, not signed in

Limit

3 an hour from one caller on one product, and 30 a day on one product

A call over its limit is refused with rate_limited and a retry_after in seconds.

Starting an investigation

start_investigation queues an investigation and returns its id. Read it back with get_investigation using that id.

If the team has no plan, Cactus is paused and an investigation is refused with this message: "Cactus is paused because the team has no plan. Pick one in Settings → Plan to turn it back on." To choose a plan, see Plans and billing.

Setting up from an AI client

The six setup tools need cactus:setup, except get_setup and get_build, which need cactus:read. Setup from an AI client may not be turned on for every team yet. If it is off for a team, its setup tools answer with a line that points to the web app.

If a call is refused

What you see

What it means

What to do

The client asks you to sign in

What it means

The call needs a token, and the address was called without one.

What to do

Sign in with your Cactus account when the client asks.

insufficient_scope: the token does not carry cactus:ask (or another scope named)

What it means

The token lacks a scope the tool needs.

What to do

Connect again and approve the scopes the sign-in lists.

not_on_team: "This tool works once they're on a Cactus team, and they aren't on one yet."

What it means

The person is not yet on a team.

What to do

Call get_setup to see where setup stands.

product_not_found: "No product … on this team."

What it means

The ref named is not one of your team's products.

What to do

Call list_products and pass one of its refs.

"Pass product: to say which"

What it means

The team has several products and the call named none.

What to do

Pass product with the ref.

rate_limited with retry_after

What it means

The caller went over its limit.

What to do

Wait retry_after seconds, then try again.

"Cactus could not reach the service that answers this. Try again in a moment."

What it means

The service behind the tool did not answer.

What to do

Try again in a moment.

Related: Team lists who is on your team, and Usage shows how many calls and answers the team has used.

Sources

Related pages