---
lang: en
---

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

> Verified against the product on 2026-11-20

> **Also on the website:** The company website's page on how an AI client reads a product's help site. [How an AI client reads your help site](<https://heycactus.ai/mcp>)

## 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` | Finds published help pages by words | Needs `cactus:read` | Anyone |
| `read_page` | Reads one help page in full | Needs `cactus:read` | Anyone |
| `list_topics` | Lists the help's sections and how many pages each holds | Needs `cactus:read` | Anyone |
| `read_timeline` | Reads the dated record of releases behind What's new | Needs `cactus:read` | Anyone |
| `search` and `fetch` | Search, then read one result in full: pages for anyone, and past conversations too for a signed-in teammate | Needs `cactus:read` | Anyone, pages only |
| `search_conversations` and `read_conversation` | Find and read past conversations | Needs `cactus:read` | Needs `cactus:read` |
| `ask` | Answers from everything the team can see, and keeps the answer as a conversation | Needs `cactus:ask` | Needs `cactus:ask` |
| `ask_help` | Answers the way the help site answers a visitor | Not offered | Anyone |
| `start_investigation` and `get_investigation` | Start a check of the product's code and read its finding | `cactus:ask` and `cactus:read` | `cactus:ask` and `cactus:read` |
| `contact_team` | Sends a message to the team as a conversation | Not offered | Anyone |
| `list_products` | Lists the team's products | Needs `cactus:read` | 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](https://cactus.heycactus.ai/a5tamg-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](https://cactus.heycactus.ai/55b9rk-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*

Working on it · Writing the answer · Answer · The turn did not finish. · Still working on it

- Working on it › the answer's first words › Writing the answer
- Writing the answer › the turn finishes › Answer
- Working on it › the turn fails › The turn did not finish.
- Writing the answer › the turn fails › The turn did not finish.
- Working on it › about 230 seconds pass › Still working on it
- Writing the answer › about 230 seconds pass › Still working on it

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](https://cactus.heycactus.ai/gg4aur-setting-up-your-first-product), and [Sources](https://cactus.heycactus.ai/ec27z4-sources) and [Builds](https://cactus.heycactus.ai/7q7w26-builds) cover what the setup calls set.

## If a call fails

| What you see | What it means | What to do |
| --- | --- | --- |
| A sign-in prompt | The tool needs a sign-in, or the page is withheld from visitors | Connect again and sign in, from [AI clients](https://cactus.heycactus.ai/766ch7-ai-clients). |
| A message that the token does not carry a scope, and a scope name | The connection lacks the scope the tool needs | 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." | The person is signed in but on no team | Call `get_setup`, or see [Joining a team](https://cactus.heycactus.ai/55b9rk-joining-a-team). |
| "This team has more than one product" and a list of refs | The call named no product on a team with several | Pass `product` with one of the refs. |
| "This team has no product yet. Create one in Cactus first." | The team has no product | Set one up, from [Setting up your first product](https://cactus.heycactus.ai/gg4aur-setting-up-your-first-product). |
| "Cactus is paused because the team has no plan." | Investigations do not start until the team has a plan | Pick a plan, from [Plans and billing](https://cactus.heycactus.ai/ajj6gc-plans-and-billing). |
| "Too many questions to this Help Center right now. Try again in" and a number of seconds | A visitor's answers for the hour are used up | Wait the seconds given. A signed-in teammate is not held to this. |
| Too many calls | The call limit for this caller is used up | Wait the seconds given. |
| "Still working on it." with a link and a `resume` value | The wait ran out before the reply was written | Call again with the same question and `resume`, or open the link. |
| "No page at" a slug "on this Help Center" | The slug is not one the caller can read | Call `list_topics` or `search_help` for the slugs that exist. |
| "Cactus could not take the question. Try again in a moment." | The question or contact was not taken | Try again in a moment. |
