> ## Documentation Index > Fetch the complete documentation index at: https://fdbad6a-heedeo-e1965c.manicule.dev/llms.txt > Use this file to discover all available pages before exploring further. > For every page in one file, fetch https://fdbad6a-heedeo-e1965c.manicule.dev/llms-full.txt (large). > To search and read these docs as tools, connect the MCP server at https://fdbad6a-heedeo-e1965c.manicule.dev/api/mcp. > Every agent surface: https://fdbad6a-heedeo-e1965c.manicule.dev/.well-known/llms-manifest.json # 11. Use Heedeo from an AI assistant (/use-heedeo-from-an-ai-assistant) Related: [Integrating Heedeo](/index.md), [Connect your app](/connect-your-app.md), [1. Quick start](/quick-start.md), [2. Serve Heedeo from your own domain (do this before you go live)](/serve-heedeo-from-your-own-domain.md), [3. One server call: evaluate or log](/one-server-call.md), [4. The fields to act on](/the-fields-to-act-on.md) Heedeo is an MCP server at `https://app.heedeo.com/mcp` (the **MCP** page in the sidebar shows it, with Copy). The assistant signs you in through Heedeo's login, in your browser, and then acts as you: it reaches every workspace you can open, and nothing else. * **Claude**: in Claude, open Settings → Connectors. Click Add custom connector and paste the server URL. Click Connect and sign in to Heedeo. * **Claude Code**: run this in your terminal: `claude mcp add --transport http heedeo https://app.heedeo.com/mcp`. In Claude Code, run `/mcp`, choose heedeo and sign in to Heedeo. * **Cursor**: add `"heedeo": { "url": "https://app.heedeo.com/mcp" }` under `mcpServers` in `~/.cursor/mcp.json`. In Cursor Settings → MCP, sign in next to heedeo. * **ChatGPT**: in ChatGPT, open Settings → Apps & Connectors → Advanced settings and turn on Developer mode. Click Create, name it Heedeo and paste the server URL. Sign in to Heedeo. **Let a coding agent do it.** The MCP page's agent prompt is one line: `Use curl to read https://app.heedeo.com/docs/mcp.md and connect the Heedeo MCP server to this agent.` Paste it into Claude Code, Cursor or another coding agent. `/docs/mcp.md` tells the agent how each client adds the server, to wait while you sign in (never to ask for a password or a key), and to check the connection with `whoami`, `list_workspaces` and `get_home`. Opening `https://app.heedeo.com/mcp` in a browser shows the URL and this prompt, each with Copy. **Workspaces.** `list_workspaces` lists yours. Every other tool takes `workspace`, an id or a name; with one workspace you can leave it out, with several the tool asks for it rather than guess. Every answer names the workspace it acted in. **What it can do**: read Home, setup status and usage (`get_home`, `get_setup_status`, `get_usage`), flags (`list_flags`) and visitors (`list_visitors`, `get_visitor`), what Heedeo answered for one event (`get_evaluation`, by its `event_id`: the answer as it was given, as `GET /v1/evaluations/:id` reads it), settings, recommendations, reliability and keys (`get_settings`, `get_recommendation`, `get_reliability`, `list_keys`, which shows a secret key's start only), the team (`list_team`) and domains (`get_domains`); decide flags as Review does, one (`resolve_flag`) or all of a person's at once (`decide_flags`), and undo a decision (`undo_decision`); label visitors (`label_visitor`; pass the label `get_visitor` showed as `expected`, and if someone changed it since, nothing changes and the error says what it is now, as a stale Trust or Block on the person's page changes nothing), split a browser (`split_browser`), delete a person (`forget_visitor`, which cannot be undone and is safe to call again: an id deleted before answers `found: false`, as `DELETE /v1/visitors/:id` answers it with nothing deleted, and an id never held is `not_found`); change what Settings changes (`rename_workspace`, `set_strictness`, `update_thresholds`, `set_action_thresholds`, `remove_action_thresholds`, `set_once`, `set_identity_step`, `set_switch`, `set_merge_declared`, `set_merge_threshold`, `set_collector_profile`, `set_auto_confirm`, `apply_recommendation`); change what Domains changes (`set_origins`, `add_hostname`, `check_hostname`, `remove_hostname`, `regenerate_prefix`, and for a Worker already deployed `redeploy_cloudflare_worker` and `delete_cloudflare_worker`); leave a workspace (`leave_workspace`); and `whoami`, `create_workspace`. An owner can also change the team (`invite_member`, `renew_invite`, `cancel_invite`, `set_member_role`, `remove_member`) and the secret keys (`create_key`, `revoke_key`, `rotate_secret_key`); a member is refused with the page's own message. Each write follows the same rules, and answers with the same messages, as the page. The prompt `triage_flags` walks the open flags one at a time, and the resource `heedeo://docs/integration` is this guide, with each section also its own resource: section 5 is `heedeo://docs/integration/5`, and Connect your app is `heedeo://docs/integration/connect`. "Flagged" means what the API's `flagged` means wherever a tool says it (`get_visitor`'s `events[].flagged` and `counts.flagged`, `get_home`'s `flagged`): never an event answered `listed: "allow"`. A trusted person's flag is still raised and listed, and each flag carries its `label` as it is now (the person's, the event's email's or its network's) and `scored`, its event as it was answered (`listed` then, and `flagged`), so an assistant sees `allow` before it decides. Neither says what the label was when a flag Heedeo raised later was raised, and a related flag has no `scored`. **Roles.** The assistant has your role on each workspace (`list_workspaces` and `whoami` say which), never more. A member is refused the owner-only tools above (the team changes and the secret keys), in the page's own words, as on the pages. A decision is recorded as yours, and Undo in Review reverses it as it does one made there. When you leave a workspace or an owner removes you, the assistant loses it on its next call. **Links and keys in the conversation.** An invite answers its link, and `create_key` and `rotate_secret_key` answer the new secret key, each once, as the page shows them. Each lands in the conversation and the assistant's history: an invite link is a credential, as a key is. Pass the link only to the person it is for and put a key straight into your server's secrets. If the conversation is shared, rotate the main key again (`rotate_secret_key`), revoke a named one (`revoke_key`), or cancel the invite (`cancel_invite`). **What it cannot do**: approve a Connect code, deploy a Cloudflare Worker or give Heedeo a new Cloudflare token, or add or change webhooks. Connect hands a terminal a secret key, and the page asks you to type the code your own terminal shows, so a code someone else sent you is not one step from a key; through an assistant the code is only text. A Cloudflare token can edit Workers in your account, so it is typed on the Domains page, never into a conversation. Use the pages for those. **Disconnect.** The **MCP** page lists the assistants with access, with when each connected and was last used. They act as you: disconnect any you don't recognize. **Disconnect** stops access at once (`403`, `disconnected`) until you press **Reconnect**. Also remove Heedeo in the assistant. To use it again, press **Reconnect** and sign in from the assistant: in Claude Code, run `/mcp` and choose heedeo. Signing out of Heedeo doesn't disconnect an assistant. ## When /mcp refuses Before any tool runs, `/mcp` itself answers these, as `{ "error": { "code", "message", "trace_id" } }` with the `heedeo-trace-id` header (section 3, "Trace id"). A request the MCP transport cannot read (a protocol version it does not speak, a body that is not JSON, a method it does not take) is answered in JSON-RPC's own shape, `{ "jsonrpc": "2.0", "error": { "code", "message" } }` with a number for `code`, with the header and no `trace_id`: | Status | `code` | What happened | What to do | | ------ | --------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------- | | 401 | `unauthorized` | No token was sent. | The assistant signs in: it follows the challenge to Heedeo's sign-in. | | 401 | `invalid_token` | The token is unknown, revoked or expired. | Sign the assistant in again. | | 403 | `disconnected` | You disconnected this assistant on the MCP page. | Press **Reconnect** on the MCP page. | | 403 | `on_hold` | The account is on hold while Heedeo takes a look at a new sign-up. | Open Heedeo to finish signing up, or reply to our email. | | 429 | `rate_limited` | Too many refused calls from one address, with a Retry-After. | Wait the Retry-After, then try again. | | 502 | `unavailable` | Heedeo could not reach its sign-in provider for the client's metadata. | Try again in a moment. | | 503 | `unavailable` | Sign-in, or the check of this connection, is unavailable for a moment. | Try again in a moment. | ## When a tool is refused A tool that cannot do what it was asked answers an error result. Its first text says why, in words to read to the person. A second text gives its code, one of these, what to do, and the request's trace id, which Heedeo's log holds for the call: `Heedeo error not_found, trace 4b1f0c7e-2d3a-4e5f-8a9b-0c1d2e3f4a5b. Check the id against what a list or get tool answered. If you ask Heedeo support, quote the code and the trace.` | `code` | What happened | What to do | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `workspace_required` | The person has more than one workspace and the call named none. | Call again with `workspace` set to one of the names or ids the message lists. | | `ambiguous_workspace` | More than one workspace has that name. | Call again with the workspace's id, from the message. | | `workspace_not_found` | No workspace of the person's has that id or name. | Call `list_workspaces` and pass one it names. | | `forbidden` | The person may not do this here: an owner-only tool for a member, or a staff-only one. | Say so to the person; an owner of the workspace can do it. | | `not_found` | Nothing of this workspace has that id: a visitor, a flag, an event or a hostname. An evaluation is kept 30 days, or as long as a flag holds its event. | Check the id against what a list or get tool answered. | | `not_enough_data` | The workspace has too little to answer this yet. | Say so to the person; ask again once more events have arrived. | | `invalid` | The call's arguments do not go together, or the change was refused. | Read the message, fix the arguments and call again. | | `refused` | The change cannot be made to this person as they stand, or (`label_visitor` with `expected`) their label is no longer the one you read. | Read the message to the person; nothing was changed. After a stale `expected`, read the person again with `get_visitor` and ask before labelling. | | `rate_limited` | Too many calls in a minute. | Wait a minute and try again. | | `internal` | Something went wrong in Heedeo. | Try again; if it keeps failing, tell Heedeo support which tool and when. |