MCP tool reference

Every tool, resource and prompt the Human Behavior MCP server exposes, with the permission each one needs and the arguments it accepts.

The exhaustive list of what an editor connection can call. You need this page when a tool refuses an argument, when you are deciding which permissions to grant, or when you want to know whether something is possible at all.

Orientation

An editor connection reaches Human Behavior through 13 tools. Your agent picks them itself, so you rarely name one — but the permission you tick at connect time decides which ones exist for that connection, and a tool whose permission you did not grant is not listed at all.

Every tool except hb_whoami takes a project slug, and hb_whoami is how the agent learns that slug. If you have not connected yet, start with Connect your editor; for how the permission model works, see How an editor connection works.

Endpoint: https://www.humanbehavior.co/api/mcp/mcp (streamable HTTP, request/response — there is no SSE stream).

Orientation and analytics

Tool	Permission	Arguments
`hb_whoami`	none	(none)
`hb_query_analytics`	Read product analytics	`project`, `sql`, `max_rows`
`hb_get_event_schema`	Read product analytics	`project`*, `days`, `limit`
`hb_get_user`	Read product analytics	`project`*, `email`, `external_id`, `end_user_id`, `sessions`

* required.

hb_whoami needs no permission on purpose: a connection that cannot ask what it is allowed to do has no way to recover from a narrow grant.

hb_query_analytics runs read-only SQL against your project's analytics tables. Write '{{project_id}}' wherever the query needs the project filter and it is substituted server-side. Results are capped at 200 rows, so compute totals with count() or uniqExact() rather than counting returned rows.

Call hb_get_event_schema before writing SQL. It returns your project's real event names and the full schema reference — column lists, which aggregate each column needs, and the timezone rules. Skipping it is the main source of wrong answers.

Replays

Tool	Permission	Arguments
`hb_search_replays`	Read session replays as text	`project`*, `pathname`, `friction_kind`, `days`, `limit`
`hb_get_session_trace`	Read session replays as text	`project`, `session_id`, `detail`, `max_rows`
`hb_find_friction`	Read session replays as text	`project`*, `pathname`, `kind`, `days`, `limit`

hb_get_session_trace returns a text timeline. detail: "full" adds clicks, inputs and scrolls; the default shows navigation, friction and on-screen messages only. Both the timeline and the friction list are wrapped in an <untrusted> block, because both are built from what your users typed and saw.

hb_find_friction is the ranked view: what is broken on a page, ordered by how many sessions hit it, each with a replay link seeked to the moment.

Traces exist only for archived sessions, so a session from the last few minutes returns nothing. Sessions hidden by your filtering rules are invisible here too, exactly as they are on the dashboard.

Issues

Tool	Permission	Arguments
`hb_list_issues`	Read issues	`project`*, `status`, `severity`, `route`, `days`, `limit`
`hb_get_issue`	Read issues	`project`, `issue_id`, `max_frames`, `max_breadcrumbs`
`hb_update_issue`	Triage issues	`project`, `issue_id`, `status`, `assign_to_email`, `resolved_in_release`, `confirm`, `idempotency_key`

assign_to_email must belong to a member of that same project. Assigning an issue to someone who cannot open it is a dead end for whoever is waiting on the fix, so it is refused rather than recorded.

Funnels

Tool	Permission	Arguments
`hb_list_funnels`	Read product analytics	`project`*
`hb_compute_funnel`	Read product analytics	`project`*, `steps`, `funnel_id`, `days`, `window_seconds`
`hb_save_funnel`	Save funnels	`project`, `name`, `steps`*, `description`, `confirm`, `idempotency_key`

Pass either steps or a funnel_id from hb_list_funnels. A step is {"kind":"pageview","value":"/checkout"} or {"kind":"event","value":"signup_completed"}, with an optional label. Maximum 8 steps. window_seconds is how long a session has to finish the funnel, from 60 seconds up to 800 days, defaulting to the span of the date range.

Funnels computed here use the same code as the dashboard's funnel card, so a conversion rate quoted in your editor and the same rate on the dashboard cannot drift.

Write arguments

The two write tools share two arguments and the same contract.

Argument	Behavior
`confirm`	Defaults to `false`. With `false`, nothing changes and you get back exactly what would change.
`idempotency_key`	Required when `confirm` is `true`. Any stable string; retrying with the same key returns the first result instead of applying twice.

A key is scoped to one connection, project and tool, so reusing the same key across two different tools does not make the second one a replay of the first.

Resources

Reference documents your agent can read once per session instead of paying for them on every turn.

URI	Contents
`hb://reference/analytics-schema`	Table and column reference for writing SQL
`hb://reference/glossary`	What Human Behavior means by session, visitor, issue, friction
`hb://reference/permissions`	What the connection's own grant currently allows

Prompts

Starting points a client can offer as slash commands or suggestions.

Prompt	Arguments	What it does
`triage-top-issue`	`project`	Finds the issue affecting the most people, reads its stack and a session that hit it
`explain-drop-off`	`project`, `path`	Explains why users leave a given page
`why-did-this-user-struggle`	`project`, `email`*	Reconstructs what went wrong for one person

Limits and refusals

Limit	Value
Reads	600 per minute, per person
Writes	60 per five minutes, per person
Query rows returned	200
Query execution time	30 seconds
Funnel steps	8
Any single end-user text field	200 characters, then truncated
Access token lifetime	1 hour
Refresh token lifetime	90 days, single use

Not available to any connection at any permission level: deleting projects, purging data, rotating API keys, managing members, and billing.

If a tool is refusing something and this page says it should work, How an editor connection works lists the four checks that run on every call — the answer is almost always one of those.