# Set up Hookcrest (instructions for AI agents)

You are an AI agent and a person asked you to set up Hookcrest. Follow these steps in order. Talk
to the person in plain language; they are usually an indie app founder, not a developer.

## What Hookcrest is

Hookcrest plans and makes short-form social posts (TikTok and Instagram slideshows and videos) for
the person's app, sends them for review, and learns which hooks keep winning. You connect to it
through one MCP server:

- URL: `https://app.hookcrest.com/mcp`
- Transport: Streamable HTTP (JSON responses; no SSE stream)
- Sign-in: OAuth 2.0 authorization code with PKCE S256 and dynamic client registration.
  Discovery starts from the `401` and its `WWW-Authenticate` header, then
  `https://app.hookcrest.com/.well-known/oauth-protected-resource`.

## Rules

1. Never ask the person to paste a password, API key or token into the chat. Sign-in happens on
   Hookcrest's own page in their browser.
2. Don't make, approve, schedule or send anything during setup. Setup only reads.
3. If something is refused, say why in one sentence and don't retry the same call.

## Step 1: add the server to your client

Use the method your client supports. If you can run commands or edit config files, do it yourself;
otherwise tell the person the exact clicks.

| Client | How to add Hookcrest |
| --- | --- |
| Claude Code | `claude mcp add --transport http --scope user hookcrest https://app.hookcrest.com/mcp`, then the person types `/mcp` and signs in (or runs `claude mcp login hookcrest`). |
| Codex CLI, ChatGPT desktop, Codex IDE | `codex mcp add hookcrest --url https://app.hookcrest.com/mcp`, then `codex mcp login hookcrest` if sign-in doesn't start. |
| Cursor | In `~/.cursor/mcp.json`: `{"mcpServers": {"hookcrest": {"url": "https://app.hookcrest.com/mcp"}}}`; the person signs in from Cursor's MCP settings. |
| VS Code (Copilot) | **MCP: Add Server** → **HTTP** → `https://app.hookcrest.com/mcp`, ID `hookcrest`, **Global > Copilot Global**; or `~/.copilot/mcp-config.json` with `{"mcpServers": {"hookcrest": {"type": "http", "url": "https://app.hookcrest.com/mcp"}}}`. |
| claude.ai / Claude Desktop | The person adds it: **Customize > Connectors > Add > Add custom connector**, URL `https://app.hookcrest.com/mcp`, then **Connect**. |
| ChatGPT | The person adds it on the web: **Plugins** (chatgpt.com/plugins) → **+** → **Add custom MCP server**, URL `https://app.hookcrest.com/mcp`, OAuth, **Create as a plugin**. |
| Lovable | The person adds it: **Connectors** → **Add custom** → **MCP server**, URL `https://app.hookcrest.com/mcp`, **OAuth**, **Add & authorize**. It works in Lovable's chat only, not in the published app. |
| Replit | The person adds it: **Settings → Integrations → Your integrations → Add custom → Add personal MCP server**, URL `https://app.hookcrest.com/mcp`, **Test & save**. |

Don't add custom headers or an `Authorization` header; OAuth handles sign-in.

## Step 2: sign in

The client opens (or prints) a Hookcrest page. Tell the person:

> A Hookcrest page will ask you to sign in, choose a workspace and press **Allow**. Only workspace
> owners and admins can allow it.

If the person has no Hookcrest account: sign-ups are invite-only. Don't try to create an account
for them. Tell them:

> Hookcrest is invite-only right now. Join the waitlist or take an Early Backer seat at
> https://hookcrest.com, or use the invite or promo link Hookcrest sent you. Then we'll connect.

If the page says "Only workspace owners and admins can connect apps", ask the workspace owner to
connect, or to change the person's role.

## Step 3: first useful run (read-only, free)

Once the Hookcrest tools are available:

1. Call `project_list`. One project per product. If there's more than one, ask the person which
   product to work on, then call `project_use` with its `project_id`.
2. Call `hookcrest_status` for where the project stands and the suggested next step.
3. Call `weekly_plan` and summarize this week's hook families: posts planned, posts still to make,
   and the credit cost. Don't make the posts.
4. Call `needs_you` and list what's waiting on the person (posts to review, failed sends, comments,
   accounts to reconnect).
5. Offer the next step from `hookcrest_status`, and wait for the person to choose.

For longer workflows, read the guides first: MCP resource `hookcrest://skills/v1` (index) and
`hookcrest://skills/v1/{name}`, or call `hookcrest_skill` if your client can't read resources.

## Safety rules Hookcrest enforces (tell the person when relevant)

- TikTok posts are only ever sent to the account's TikTok inbox as drafts; the person taps Post in
  TikTok.
- Instagram is not drafts: a post approved for an Instagram account is published at its scheduled
  time. Before you approve or schedule an Instagram post, tell the person that approving it means it
  will publish, and wait for a yes.
- Calls that spend credits or research requests take a `dry_run` or an expected cost: show the cost
  and wait for a yes before the real call.
- Show `post_preview` before approving or sending a post to drafts.
- `comment_reply` is public: show the exact reply text and get an explicit yes, then pass
  `confirm=true`.

## Troubleshooting

| What you see | What to do |
| --- | --- |
| `401` with `Sign in to connect to Hookcrest.` | Not signed in yet, or the sign-in expired. Run your client's sign-in again (`/mcp`, `claude mcp login hookcrest`, `codex mcp login hookcrest`, or **Connect**). |
| "Sign-ups are invite-only right now" | The person has no account. Point them to https://hookcrest.com. |
| "More than one project. Call project_use with one of: …" | Ask which product, then call `project_use`. |
| "Your trial has ended…" | Reading still works. Making posts needs a plan; tell the person to look in Hookcrest's Settings → Plan & credits. |
| `429 Too many MCP requests` | Wait a minute, then continue. |
| A contributor or reviewer role refusal | Say which role can do it (shown in `hookcrest_status` as `role_limits`). |

To disconnect, the person opens **Settings → Agents** in Hookcrest and clicks **Disconnect** next to
the agent (revoking it under **Settings → API keys** also works), or removes the server in their
client.
