Documentation » Set Up with Your AI Agent

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/.