Help › Fixing

Connect your AI coding tool to Kartafla

Point Claude Code, Cursor or any MCP client at your account so it can read your site readiness and apply the fixes itself.

Last updated 2026-09-08

Kartafla finds what is holding your brand back in AI answers, and writes the fixes. Until now the last step was yours: copy a robots.txt, paste some JSON-LD, edit your hero. If your site is a repository you already have open in a coding agent, that step can be the agent's instead.

Kartafla never touches your site. It serves the diagnosis and the fix content; your agent, running on your machine with your permissions, does the applying. Nothing here gives us access to your code, your server or your deployments.

Before you begin

• A Kartafla account on a paid plan — Starter, Growth or Agency.
• A coding agent that speaks MCP: Claude Code, Cursor, Codex, Windsurf, Zed and others.
• Node 20 or newer, which the package runs on.

1. Create an API key

In Kartafla, go to Settings, then API keys, then Create key. Give it a name that says where it lives — "Claude Code, work laptop" — so you know which one to revoke later.

The key is shown once. We store only a hash of it, so we genuinely cannot show it to you again. Copy it somewhere safe before closing the dialog.

2. Connect your tool

In Claude Code, run this in your project:

claude mcp add kartafla --env KARTAFLA_API_KEY=kf_live_… -- npx -y kartafla-mcp

For any other MCP client, add this to its config file and restart it. Where that file lives differs per tool — check your client's own MCP documentation rather than guessing.

{
  "mcpServers": {
    "kartafla": {
      "command": "npx",
      "args": ["-y", "kartafla-mcp"],
      "env": { "KARTAFLA_API_KEY": "kf_live_…" }
    }
  }
}

3. Keep the key out of your code

The key belongs in the config's env block or in an environment variable on your machine. Never paste it into a file you commit. Anyone with the key can read every brand, question and result in your account.

A key reaches one account: the one that created it. If you are also a member of someone else's Kartafla account — a client's, say — your key cannot see their brands, and theirs cannot see yours. Sharing an account with someone does not share your agent's access to it.

If you think a key has leaked, revoke it in Settings. Revocation takes effect on the very next request — there is no cache to wait out.

4. Tell your agent the house rules

Agents work better with standing instructions than with a long prompt each time. If your project has a CLAUDE.md or equivalent, this is worth adding to it:

## Kartafla

Use the kartafla MCP tools to check AI visibility before and after content changes.

- get_site_readiness before editing anything, so there is a baseline.
- Only write fixes marked safe_to_apply.
- needs_input means blanks: ask me about each one, never invent a value.
- review_first means draft copy: show it to me and wait for a yes.
- human_only is an outline for a person. Never write it to a file.
- Site readiness reports what is PUBLISHED. Re-check after deploying, not after editing.
- mark_fix_applied only after it is deployed. It is a claim about my live site.
- Ask before generate_fixes or run_visibility_check. Both spend my money.
- Never run a visibility check to see if a fix worked — engines take days, and it
  spends my monthly check. Use run_site_check, which is free.

5. Your first prompt

Paste this into your agent, with your own domain:

Read my Kartafla site readiness for example.com, then apply every fix marked
safe_to_apply to this repo. For anything marked needs_input, ask me about each
blank before writing. Skip anything marked human_only.

What your agent may and may not apply

Every fix carries a policy. This is not advice in a doc — the API returns it on each fix, and the tool descriptions repeat it, so a well-behaved agent will follow it without being reminded.

• safe_to_apply — a file or markup block with nothing missing. Your agent can write it.
• needs_input — the draft contains blanks in square brackets, usually facts we were never given. Every one needs your answer first.
• review_first — nothing is missing, but it is copy about your business. You should read it and mean it before it ships.
• human_only — an outline for a person to write from. There is nothing to paste.

What your agent can change in Kartafla

Five of the tools write, and all five act on your Kartafla account rather than your site: recording a fix as applied or dismissed, re-checking your site, generating fixes, and running a visibility check. The last two spend money, so the tools refuse to run until you have said yes.

Marking a fix applied is a claim about your live site, so the server checks it. If the fix still contains blanks, the call is refused until your agent can tell us what each one should say — which means it had to ask you. An article brief cannot be marked applied at all; there is nothing to apply, so that one stays in the dashboard.

Nothing here reaches your billing, your subscription, your team, or another account. Those routes are refused for any key, whatever scope it has.

Best practices

• Review every tool call, especially anything that writes. This agent edits your website.
• Use your tool's plan mode for the first run, so you see the shape of the work before any file changes.
• Re-run the site check after deploying. Readiness reports what is currently published, not what is in your working tree.
• A fix marked human_only or review_first is not the tool being unhelpful. It is the part a person has to do, and pretending otherwise is how a placeholder ends up on a live pricing page.
• Use one key per machine. Then revoking a laptop does not break your CI.

Troubleshooting

• "KARTAFLA_API_KEY is not set" — the variable did not reach the process. It belongs in the env block of your MCP config, not in your shell profile.
• 401, invalid or revoked — the key was revoked, or regenerated. Regenerating replaces the secret immediately; paste the new one into your config.
• 403, this endpoint cannot be called with an API key — expected. A key can read everything, apply or dismiss a fix, and run a check. Billing, your account and other people's data are refused by design, whatever scope the key has.
• 422, this fix still has N blanks — your agent tried to mark a fix applied without answering the facts nobody supplied. Ask it to ask you, rather than to invent them.
• 403, writes are disabled because this account has no active paid plan — reads keep working when a plan lapses. Writes do not.
• 429 — this key has its own rate budget, separate from the dashboard, so an agent in a loop cannot lock you out of your own account. Wait a minute.

What this does not do

It does not deploy. It does not open pull requests. It does not talk to your host, your CMS or your DNS. Everything it changes, it changes in the files your agent already has access to — which is also why you should read what it did before you ship it.

Related

• llms.txt, explained
• robots.txt and AI crawlers
• The schema markup worth adding
• What to do when the fix isn't on your website