Connected agents

Hookie runs a hosted MCP server. Point an AI coding agent (Claude Code, Cursor, or any MCP client) at one URL and it can do, on your behalf, the things you would otherwise do in the console: create endpoints, write routing rules, point events at a destination, read records back, and replay a failed delivery. Nothing is installed and nothing is pasted anywhere. The agent signs in as you, starts out read-only (unless you signed up through it), and you decide in the console what more it may do. You can cut it off again in one click.

Hookie has no chat assistant of its own: you bring your agent. In the console, Connect an agent in the top bar (next to the theme switch and your profile) shows your MCP URL, the Claude connector, and the Claude Code command in one place.

The hookie CLI is the same connection from a terminal instead: the same OAuth flow, the same credential store, and commands generated from the same catalog you see below — so anything an agent can call, you can run by hand.

Connect one

Hookie hosts the MCP server. There is nothing to install; point your agent at:

https://app.hookie.ai/mcp

For Claude Code that is one command; or, in an .mcp.json that you can commit to a repo:

claude mcp add --transport http hookie https://app.hookie.ai/mcp

{
  "mcpServers": {
    "hookie": {
      "type": "http",
      "url": "https://app.hookie.ai/mcp"
    }
  }
}

For Claude on the web or desktop, add Hookie as a custom connector: open Settings → Connectors, choose Add custom connector, and paste the URL above. Claude then signs in to Hookie as you, the same way. No credential goes in that file, because there isn’t one to put there. The first request your agent makes is refused with a pointer to Hookie’s authorization server (WorkOS AuthKit, the same place you sign in). The agent registers itself there, opens a sign-in in your browser, and from then on holds a token it refreshes on its own. That is the standard OAuth 2.1 authorization-code flow with PKCE, the same one you would get from any well-behaved MCP client. You do not need a Hookie account first. If you have never signed in to Hookie, sign up on that same page (email code, Google or GitHub): the first time your agent calls Hookie, your account and a Free workspace are set up for you, exactly as a first console sign-in would. Because that agent is how you joined, it starts able to build (create and change endpoints, rules, destinations and the rest), not read-only; administering the workspace still needs the console. Any agent you connect after that starts read-only as usual. Sign in to the console with the same method to change what each agent may do.

For something that runs unattended, such as a CI job or your own backend, with nobody at a browser to sign in, create an API key instead. /mcp accepts it as a bearer token, and its role decides which tools it can call.

For an agent that should have a Hookie account of its own, with no person signing in at all, see Agent self-registration. The agent registers itself on the Free plan and gets an admin API key, and a person can claim the workspace later.

What it may do

Signing in proves who the agent is acting for. What it may do is decided separately, by you, in Settings → Connected agents. A newly connected agent can only read until you grant it more, and the change takes effect on its next call. Access is one level of three, and each includes the one before it. Choose it with Change access beside the agent; the dialog says what each level allows.

Level	Scope	Lets the agent…
Read only	`hookie:read`	Read the workspace: projects, datasets, records, endpoints, rules, destinations, deliveries, triggers, workflows and the member list.
Read and write	`hookie:write`	Also create, change and delete endpoints, rules, destinations, workflows, sources, AI triggers, AI agents and the customer portal. Equivalent to the developer role.
Administer	`hookie:manage`	Also projects, cron and WebSocket triggers, and workspace administration: the IP allowlist and the audit export. Equivalent to admin, except that it never reaches invites or member changes.

An agent is never a principal of its own. It acts as you, and its authority is your workspace role narrowed to the scopes you granted; whichever is more restrictive wins. An agent granted hookie:manage by someone with the viewer role is still a viewer.

Three things it can never do

Touch billing. Subscribing, cancelling, and changing a card are unreachable at every scope. Those stay decisions a person makes.
Change who is in the workspace. Inviting someone, changing a role, removing a member and transferring ownership are refused at every scope. An invite link gives a person access, so only a person in Settings → Members can create one. An agent can read the member list with list_members. See Team members.
Destroy data in bulk. There is no tool to delete a project, purge a dataset or close the workspace. An agent manages routing configuration, which is visible and undoable; bulk, irreversible deletion stays in the console, where it has to be typed out. Two tools can remove something for good, and both are marked destructive so your client asks you first: delete_record, which erases a single record by id (for an erasure request, or a secret posted by mistake), and delete_workflow with permanent: true, which deletes one workflow and its run history. Records and deliveries the workflow’s runs produced are kept.

Every action an agent takes is written to your audit log with you as the actor and the agent’s client ID recorded alongside, so “who deleted this endpoint” always has an honest answer.

When an agent is refused

A call above the agent’s level is refused with what to do about it, not a bare “Insufficient role”. The 403 names the scope the call needs and the one the agent holds, and links to Settings → Connected agents opened on that agent:

{
  "error": "This needs hookie:write, and this agent is approved for hookie:read. Ask your user to widen its access in the Hookie console under Settings → Connected agents (https://app.hookie.ai/#/settings/agents?client=…); it applies on the next request, with no need to reconnect.",
  "code": "agent_scope_insufficient",
  "required_scope": "hookie:write",
  "granted_scopes": ["hookie:read"],
  "manage_url": "https://app.hookie.ai/#/settings/agents?client=…"
}

Over MCP the same sentence comes back as the tool’s error, so the agent can hand you the link. Widening applies to its very next call, with no reconnect. Every agent is shown the full tool list whatever its scope, so a read-only agent can see the write tools; calling one before it is widened gets this refusal. Two refusals carry no link, because widening would not help:

code: "insufficient_role" — your own role does not allow the call, and an agent can never do more than you, so widening its access will not help. A workspace owner or admin has to change your role first, in Settings → Members. The error names your role and links there:

{
  "error": "This needs hookie:manage, and your own role on this workspace (developer) does not allow it. An agent can never do more than its user, so widening this agent's access will not help: a workspace owner or admin has to change your role first, in the Hookie console under Settings → Members (https://app.hookie.ai/#/settings/members).",
  "code": "insufficient_role",
  "required_scope": "hookie:manage",
  "granted_scopes": ["hookie:read", "hookie:write", "hookie:manage"]
}

code: "agent_not_permitted" — no agent may do this at any level: billing, platform administration, managing connected agents, invites and member changes, switching workspaces, and revealing or rotating a destination’s signing secret.

Revoke

Settings → Connected agents in the console lists everything you have connected, what each may do, and when it last acted. Revoking takes effect on the agent’s next call, even though its token is still valid, because Hookie checks its own grant on every request. Agents that call Hookie with a user-delegated WorkOS Agent Auth token are listed here too, as WorkOS agent, and follow the same rules: read-only until you widen them, revocable at once. See WorkOS Agent Auth.

Tools

Every agent is shown every tool. Each table names the scope a call needs, and a call above the agent’s scope is refused as described under When an agent is refused. Needs hookie:read:

Tool	What it does
`get_workspace`	The workspace’s slug, id, your role and plan. The slug is the first segment of every public endpoint URL.
`list_members`	The people in the workspace: `user_id`, `email`, `name`, `role` and `joined_at`, owner first, and the plan’s `max_members` (`null` for unlimited). Read-only: there is no tool to invite, change a role or remove anyone.
`list_projects`	The workspace’s projects.
`get_project_overview`	A project’s details plus its dataset summary.
`list_datasets`	Datasets in a project, with record counts.
`query_records`	One page of a dataset’s records (optionally through a saved view), with the whole count, for `limit`/`offset` paging.
`list_record_views`	Saved table views, per dataset: which fields matter, what they are called, how they sort.
`get_record`	One record in full, including fields a view left out.
`list_webhooks · list_rules · list_destinations`	A project’s routing configuration. Endpoints come with a ready-to-send `public_path`.
`get_webhook_activity`	One endpoint’s received and refused requests over the last 7 days, with the reason each refusal got. The call to make when a provider reports an error.
`list_sources · list_triggers`	Database sources (never their connection string), and AI triggers.
`list_cron_triggers`	Cron triggers: schedule, time zone, payload, dataset, last and next run.
`preview_cron_schedule`	The next five fire times of a schedule, before anything is saved — or why it cannot be stored.
`list_ws_triggers`	WebSocket triggers and their connection status. Never the URL’s headers.
`list_ai_agents · get_ai_agent`	AI agents — the named model configurations a workflow’s `agent_call` step runs.
`get_portal · list_portal_tokens`	The project’s customer portal, and the customer links issued for it (prefix only, never the token).
`list_ingest_keys`	Ingest keys as metadata only — name, prefix, last used, expiry, status. Never the plaintext.
`list_deliveries`	Recent outbound deliveries: status, response code, and destination.
`list_held_deliveries`	Events whose deliveries are held because the monthly delivery allowance is used up, oldest first, with this month’s usage.
`get_delivery`	One delivery in full: the stored response body and every attempt it made. The only call that returns them.
`get_delivery_metrics`	Delivery health per destination over 24 hours, 7 or 30 days: success rate, p50/p95/p99 latency, failed attempts by class, and a time series.
`search_deliveries · search_events · search_submissions`	Filtered, paged search with a time window. Use these rather than the `list_` tools for anything but a glance.
`list_workflows · get_workflow`	Workflow definitions in a project.
`export_project_config`	A project’s configuration as one document: endpoints, rules, destinations, AI agents, workflows, AI triggers, cron triggers and record views. No endpoint URLs, signing secrets or keys.
`list_workflow_runs · get_workflow_run`	Execution history, including which branch each instance took.
`send_test_event`	POST a sample payload to a public endpoint URL.

Needs hookie:write:

Tool	What it does
`create_webhook · update_webhook · delete_webhook`	Endpoints. Create needs only a `name`: the `slug` is made from it when left out, and the `dataset` defaults to the name as an identifier, or `default`. Update changes enabled, name, dataset, the IP allowlist, the form redirect URL, the allowed browser origins, the URL verification it answers and its provider signature verification. The tool tells the agent to ask you for the provider’s signing secret rather than invent one; it is never returned.
`rotate_webhook_verification_secret`	Replace the provider signing secret an endpoint verifies with, keeping the old one verifying for `overlap_hours` (default 24; 0 ends it at once). Neither secret is returned.
`create_webhook_version`	A new version of an endpoint with its own URL, criteria, mappings or dataset; the old version keeps working. `slug` is the endpoint’s `base_slug`. Change or retire a version with `update_webhook` / `delete_webhook` on its id.
`rotate_webhook`	A new URL for an endpoint, with the old one kept for an overlap. The response carries the new URL, which is a credential.
`create_rule · update_rule · delete_rule`	Mapping rules. Update changes any field — name, enabled, dataset, conditions or mappings — and sends only what changes. Conditions take all ten operators.
`import_project_config`	Create in a project what an `export_project_config` document describes, with new endpoint URLs and signing secrets. Anything that already exists is skipped, never overwritten. See Export, import and clone.
`create_record_view · delete_record_view`	Saved table views on a dataset, the same ones people see on the console’s Datasets tab.
`create_destination · update_destination · delete_destination`	Outbound sinks. Create takes a `type`: `webhook` (the default) needs an https `url`; `slack` and `s3` take `config` instead, and no `url`, `headers` or `auth`. Slack’s `config` is `{webhook_url}`; S3’s is `{endpoint?, region, bucket, prefix?, access_key_id, secret_access_key}` (see Destination types and options). A `hooks.slack.com` URL is refused as a webhook’s `url`. `config.webhook_url` and `config.secret_access_key` are write-only, and the tool tells the agent never to echo them. Update renames a destination or moves it to a new https URL (same id and signing secret; a portal customer’s keeps its URL), changes a Slack or S3 destination’s `config` (settings and credentials left out keep their stored values; the type cannot change), and changes enabled, the dataset filter and the delivery limits (`timeout_seconds`, `max_per_second`, `max_concurrency`; `null` restores the default). An empty filter is refused; leave it out for every dataset.
`create_workflow · update_workflow`	A multi-step workflow: entry dataset, entry conditions, and the ordered steps. A multi-step workflow — entry dataset, entry conditions, and the ordered steps. Update is a full replace, not a patch: read with `get_workflow`, edit, send it all back.
`delete_workflow`	By default this deactivates: the definition and its run history stay, and `update_workflow` with `active:true` turns it back on. With `permanent: true` it deletes the workflow and its run history for good. It is refused while a run has not finished, and the error names the runs to cancel with `cancel_workflow_run`.
`cancel_workflow_run · retry_workflow_run`	Stop a running or waiting workflow run, or retry one that failed, timed out or was cancelled.
`release_held_deliveries`	Send held deliveries, oldest first, while the allowance covers them. Stops at the first event it can’t fully cover.
`replay_delivery`	Re-queue a past delivery to its destination.
`replay_deliveries`	Replay every delivery that did not arrive, by destination, status and time range, in bounded passes: call again while `more` is true. `dry_run` counts without sending. Charged to the delivery allowance and stops when it runs out.
`create_ingest_key`	A new ingest key, optionally with an expiry and an IP allowlist. Returns the plaintext once, so treat it as a credential.
`update_ingest_key`	Rename a key, or set or clear its expiry or IP allowlist.
`rotate_ingest_key`	Issue a replacement key and keep the old one working for an overlap. Returns the new plaintext once.
`revoke_ingest_key`	Kill a key. It stops authenticating on the next request; the row and its audit trail survive. Not reversible.
`create_source · update_source · test_source · delete_source`	Database sources: a Postgres table (`config: {url, table}`) polled into a dataset. The connection string is encrypted and never returned. Update pauses or resumes; test checks the connection without storing anything. Needs the Pro plan.
`create_trigger · update_trigger · delete_trigger`	AI triggers: records in a dataset that meet the conditions run the model with your `instructions`, and each reply is stored in `output_dataset`. Update toggles enabled.
`create_ai_agent · update_ai_agent · delete_ai_agent`	AI agents. Update changes only the fields you pass; delete retires the agent (inactive), and update with `active: true` brings it back.
`update_portal · delete_portal`	The project’s customer portal: update creates it the first time, then changes its name, exposed datasets or enabled; delete switches it off, and update with `enabled: true` turns it back on.
`create_portal_token · revoke_portal_token`	A customer’s link to the portal, and cutting it off. Create returns the token once, so treat it as a credential.
`delete_record`	Permanently erase one record and every copy Hookie keeps of it: its raw submission, deliveries and their responses, held deliveries, the workflow runs it started and AI output made from it. Returns what was deleted. Not reversible; see Delete, export and close.

The hosted server doesn’t offer a tool that tails live events, because a tool call should return promptly rather than hold a connection open. To tail events, read the live stream with an ingest key. Needs hookie:manage — the routes the console keeps to owners and admins:

Tool	What it does
`create_project`	A new project.
`create_cron_trigger · update_cron_trigger · test_cron_trigger · delete_cron_trigger`	Cron triggers: a payload emitted on a schedule (five cron fields, at least 5 minutes apart, in an IANA time zone). Update changes any field; test fires it once, now, as a real event.
`create_ws_trigger · update_ws_trigger · test_ws_trigger · delete_ws_trigger`	WebSocket triggers: an outbound connection whose matching frames become events, optionally reshaped by `mappings` the way a rule’s are. Headers are encrypted and never returned. Update changes any of `name`, `enabled`, `url`, `headers`, `subprotocols`, `connect_message`, `conditions` and `dataset` in place, keeping the trigger’s id, status and last error (send `null` to clear headers, subprotocols, connect message or dataset; `mappings` cannot be changed in place). Test returns the first frames without storing anything.

There is no create_dataset, because a dataset is not something you create. A dataset is a name records carry: it exists the moment the first record is routed into it, and the console has no way to make an empty one either. Name it in a rule, an endpoint, or a workflow’s entry_dataset and it appears. Every tool carries MCP annotations, so a client can tell at a glance which calls are safe. readOnlyHint is derived from the tool’s required scope rather than maintained by hand, so it cannot disagree with what the tool is allowed to do. destructiveHint is set where something can be unrecoverable: delete_webhook, delete_rule, delete_destination, delete_record_view, delete_record, revoke_ingest_key, and delete_workflow, whose permanent: true deletes for good. An annotation covers the whole tool, so a client may ask to confirm a plain deactivation too. It is deliberately not set on replay_delivery and replay_deliveries, which re-send: prompting for confirmation on a reversible action trains people to click through the ones that matter.

Addressing an endpoint you just created

An endpoint’s public URL is {workspace}/{project}/{endpoint-slug}, and the endpoint slug is a high-entropy value the server mints — not the readable slug you passed in, which is stored as base_slug and never appears in a URL. You do not have to assemble any of that. create_webhook and list_webhooks both return public_path and public_url, and public_path is exactly the string send_test_event takes:

{
  "id": "97249267-…",
  "base_slug": "orders",
  "version": "1",
  "webhook_slug": "aBcXyz0123456789abcdefgh",
  "public_path": "acme-3f9a/orders/aBcXyz0123456789abcdefgh",
  "public_url": "https://app.hookie.ai/acme-3f9a/orders/aBcXyz0123456789abcdefgh"
}

webhook_slug is the credential — anyone holding it can post events to your workspace, which is why the URL needs no other authentication. So are public_path and public_url, which contain it. base_slug and version are the readable identity and are safe to log.

If you do need the pieces, get_workspace gives the first segment. A wrong path and a disabled endpoint both answer the same 404, so check enabled before assuming the URL is wrong. update_webhook is narrower than it sounds, deliberately. An endpoint’s public URL is its credential, and its criteria and mappings define what it has already ingested; changing those in place would quietly reinterpret history. To change them, publish a new version with create_webhook_version, or rotate the URL with rotate_webhook. A destination is different: update_destination can rename it or move it to a new URL, and it keeps its id and signing secret, so its receiver keeps verifying.

Bringing your own client

The hosted server speaks MCP’s Streamable HTTP transport at https://app.hookie.ai/mcp: POST JSON-RPC, no session header required. Authentication is standard OAuth 2.1, so any client that speaks it can connect without an MCP library. Start with our protected-resource document, which names the authorization server to register with:

GET  https://app.hookie.ai/.well-known/oauth-protected-resource   # RFC 9728 — names the authorization server
GET  <issuer>/.well-known/oauth-authorization-server            # RFC 8414 — endpoints, PKCE methods
POST <issuer>/oauth2/register                                   # RFC 7591 — dynamic client registration
GET  <issuer>/oauth2/authorize                                  # authorization code + PKCE (S256 required)
POST <issuer>/oauth2/token                                      # code → access + refresh token

Ask the authorization server only for the scopes it advertises (openid, profile, email, offline_access). Hookie’s own hookie:* scopes are not requested there. They are granted by you in the console, and asking WorkOS for them fails the authorization outright.

PKCE is required, because agents are public clients that cannot keep a secret and the authorization code travels through a terminal. Registration is open because agents are installed per developer rather than registered by us ahead of time; a freshly registered client can only read until a human grants it more in the console. Hookie is the resource server: it verifies the access token offline against WorkOS’s signing keys, then applies the grant you set. The token authenticates the same /admin/api/* routes the console itself calls, so there is no second, weaker API to learn.

Get started

Concepts

CLI

Guides

API reference

Connected agents

Connect one

What it may do

Three things it can never do

When an agent is refused

Revoke

Tools

Addressing an endpoint you just created

Bringing your own client

​Connect one

​What it may do

​Three things it can never do

​When an agent is refused

​Revoke

​Tools

​Addressing an endpoint you just created

​Bringing your own client

Connect one

What it may do

Three things it can never do

When an agent is refused

Revoke

Tools

Addressing an endpoint you just created

Bringing your own client