# Kafkai onboarding: instructions for the AI agent

If you are a person reading this: this page is written for your AI agent. Paste this line into Claude, ChatGPT or any MCP client:

> A Kafkai customer pasted this link into you. Your job is to take them
> from "no connection" to "first project with data". Ask one question at a
> time. Reply in the language the customer writes in.
> `Read https://kafkai.com/docs/onboarding.md and set up Kafkai for me.`

## Stage 1: connect Kafkai to this client

First check whether you already have tools whose names start with
`kafkai_`. If you do, skip to Stage 2.

If you do not, the customer adds the connection by hand in the client's
settings. You cannot do it for them, except in Claude Code. Ask which
client they use and give only the steps for that client. The server URL
is always `https://kafkai.com/mcp`.

- **claude.ai or Claude Desktop**: Settings → Customize → Connectors →
  Add. Enter a name and the server URL, keep the detected sign-in
  settings, choose Add, then Connect, and allow access on the Kafkai
  page that opens.
  Full guide: https://kafkai.com/en/docs/connect-claude/
- **Claude Code**: run the command below (you may run it yourself if the
  customer agrees). Then the customer restarts `claude`, runs `/mcp`,
  and signs in. A connector already added in claude.ai is picked up
  automatically when Claude Code is signed in with that account.
  `claude mcp add --transport http kafkai https://kafkai.com/mcp`
- **ChatGPT**: needs a plan that allows custom plugins. Settings →
  Security → turn on Developer mode. Then Plugins → **+** → name
  "Kafkai", the server URL, authentication OAuth → Create → sign in to
  Kafkai and choose Allow. Enable the plugin from the tools menu of the
  chat. Full guide: https://kafkai.com/en/docs/connect-chatgpt/
- **Hermes and other clients**: the customer creates an API token at
  https://kafkai.com/en/accounts/api-tokens/ and puts the server URL and
  the token in the client's config.
  Snippets: https://kafkai.com/en/docs/connect-hermes/

If the menus do not match, send the customer to the full guide. It has
screenshots.

When the connection is added, tell the customer to start a new
conversation and paste the same line again. Stop here.

## Stage 2: set up the first project

You do this part with the Kafkai tools. Every tool response carries a
`next_step_suggestion` field. Follow it.

1. Call `kafkai_get_credit_balance`. It is free. Then call
   `kafkai_list_projects`, which is also free. If a project already
   exists, ask whether to use it and skip to step 6.
2. Ask for the site URL, then the country the site targets, then
   competitor sites. Competitors are optional and can be added later.
   Never guess the country. A project is locked to one country's search
   results.
3. The description of `kafkai_create_project` states the price: one
   amount for the site plus one amount for each competitor. Tell the
   customer the total in credits and compare it with the balance. If the
   balance is too low, point to https://kafkai.com/en/pricing/ and stop.
4. When the customer agrees, call `kafkai_create_project`. Research runs
   in the background and takes a few minutes.
5. While research runs, use the time:
   - If the customer gave no competitors, offer
     `kafkai_find_competitors`. Say what it costs before you call it.
   - Ask whether the site is theirs. If it is, offer the
     `setup_steps` from the `kafkai_create_project` response, in order.
     They are free and unlock the site's Search Console, Google
     Analytics, analytics and Bing Webmaster Tools data. The first is domain
     verification: call `kafkai_verify_domain` and show both the DNS
     TXT record and the meta tag exactly as returned, so the customer
     can publish whichever one they can. After the customer adds one of
     them, call `kafkai_check_domain_verification`. The customer can
     also check at https://kafkai.com/en/accounts/domains/. The other
     steps need verification first. A step already done is not listed.
   - Steps the customer skips come back as `setup_reminders` in
     `kafkai_list_projects` and `kafkai_get_project_summary`. Offer
     them from the summary: it has the final answer. If the
     customer does not own the site, or does not use one of the
     services, offer to stop that reminder: each reminder's `mute`
     gives the exact `kafkai_update_project_settings` call. It is free
     and disconnects nothing.
6. Call `kafkai_get_project_summary`. It is free. Check at most once a
   minute. While `status` is not
   `Ready`, or `last_research.status` is `pending`, research is still
   running. A new project has no `last_research` yet, so read `status`.
   Wait a minute or two and ask again. Do not call `kafkai_update_keywords`.
   It starts a new paid research run.
7. When research has finished, offer these three first questions and
   answer the one the customer picks:
   - Which keywords should we write about next, and why?
   - How does our strongest competitor beat us, and what closes the gap?
   - What does the site already rank for that we should protect?

More prompts: https://kafkai.com/en/prompts/
Tool reference: https://kafkai.com/en/docs/tools/

## Rules

- Say the credit cost before every call that spends credits, and wait
  for the customer to agree.
- Never start a research update unless the customer asks for one.
- Mention `setup_reminders` once per session, not on every call.
- Never ask the customer to paste a password or an API token into this
  conversation.
- If a tool returns an error, show the customer the message and point
  to https://kafkai.com/en/docs/troubleshooting/.