Kleap MCP Server

Use this when the user wants a complete, hosted website or web app built from a text description (e.g. 'build me a website for X'). Kleap's AI builds AND auto-deploys the whole site; this takes a few minutes (typically 5 to 15 min). Returns a build_url instantly so the user can watch it build live. In a widget client (ChatGPT Apps) the preview above shows real-time progress and reveals the final live URL by itself, so you do NOT need to block or keep polling check_task. Prefer this over write_files for full-site creation.

Resolve a website the user refers to by its ADDRESS — a custom domain ('mysite.ch'), a kleap.io URL ('mysite.kleap.io'), or a slug — to its app_id. Use this FIRST whenever the user names a site by its address instead of an app_id (e.g. 'edit mysite.ch'), then pass the returned app_id to get_app / modify_app / publish_app. ADDRESS TO SHOW THE USER: site_url. When the owner has connected a domain, custom_domain is set and site_url is that domain — say THAT, never the {slug}.kleap.io host, which is the internal address they did not choose.

Show a website to the user: its screenshot, name and live address. This is the ONE tool that renders the finished-site card, so call it once after a build or edit has finished and deployed (check_task says deployment_status deployed) — that is what lets the user SEE what was built. Also use it for plain details: name, slug, URLs, creation date, status. ADDRESS TO SHOW: site_url. If custom_domain is set, the owner connected that domain and it IS their site's address — never hand them the {slug}.kleap.io host instead, they did not choose it. Never call this while a build is still running: it would show the previous version as if it were the new one.

List the source file PATHS of an app (names only, no contents). See the project structure, then read_files to get contents before editing. Astro: src/pages/*.astro, src/data/*.json, src/components/*.astro, public/*.

Remove pages, components or assets from a site — the counterpart to write_files. Use it when a page should no longer exist: a wrong route, a duplicate, an outdated landing page, an image nobody references. Do NOT overwrite the file with empty content instead: that leaves a URL answering 200 with nothing, which is worse for SEO than a clean 404. Deleting a binary also removes its stored bytes. Paths Kleap owns (astro.config.mjs, package.json, tsconfig.json…) are refused — the build lays its own copy back down, so removing them changes nothing. The homepage (src/pages/index.astro) is refused too: a site with no homepage is broken — write a new one instead, writing replaces it. Returns which paths were actually deleted and which did not exist. The pages STAY LIVE until you call publish_app.

Read existing file contents so you can edit them SAFELY instead of rewriting blind (which risks breaking shared components/homepages). Loop: list_app_files → read_files → edit_files (change just the lines that must change) → publish_app; use write_files instead only when you are writing a whole new file. Use it to fix headers/footers, wrong phone numbers, broken links, dead forms. Works with a Read-only key. Returns { files: [{ path, content, type, bytes, truncated?, returned_bytes? }], missing }. Text is capped at 256 KiB per file and 1 MiB per call; truncated files are explicitly marked, and files beyond the call budget must be read separately.

Write WHOLE files DIRECTLY — YOUR model generates the code, Kleap stores, builds and deploys it as-is. To change something in a file that ALREADY EXISTS, use edit_files instead (read_files → edit_files): it replaces just the lines you name, while write_files makes you retype the entire file and silently drops whatever you leave out — on a 30KB shared layout that is how headers and footers get wiped. No Kleap-AI step, so what ships is byte-for-byte what you wrote — the right choice when a phrase, a URL or a schema must be exact. Publishing still audits the result (see publish_app). Best for scaffolding exact pages/components — e.g. programmatic-SEO routes. Astro paths (src/pages/*.astro, src/data/*.json, src/components/*.astro, public/*). Overwrites by path. NPM PACKAGES: do not write package.json (the build replaces it) — the build installs whatever your code IMPORTS, so `import { jsPDF } from "jspdf";` is all it takes. Supported on import: @tiptap/*, jspdf, pdf-lib, html2canvas, papaparse, file-saver, jszip, @ffmpeg/*, howler, wavesurfer.js, browser-image-compression, react-dropzone, recharts, chart.js, d3, @tanstack/*, react-hook-form, three, @react-three/*, leaflet, maplibre-gl, gsap, framer-motion, zustand, date-fns, react-markdown, axios, socket.io-client, radix-ui/*, next-themes, lucide-react, @tabler/*, openai, @ai-sdk/*; anything else is refused at build with a message naming it. A client-side router is never the answer — a route is a FILE (src/pages/about.astro → /about). IMAGES AND BINARIES: set encoding:"base64" on the file and send the bytes — that is how you put a logo, a photo, an OG image, a favicon or a font on the site (png/jpg/webp/svg/ico/mp4/woff2/pdf, 512KB max each decoded). Without it you can only write text, and a site with no images looks unfinished. To ADD an image from a text prompt WITHOUT sending any bytes (a real photo's base64 is too big to emit reliably), use generate_image — Kleap generates it and stores it for you. To REMOVE a page or asset, use delete_files — overwriting it with empty content leaves a URL that answers 200 with nothing, which is worse than a 404. DATA & ACCOUNTS: write_files only STORES files — it cannot provision the Kleap Database, so DB or auth code pushed here has no backend and silently does nothing. Stand the feature up with modify_app first, then edit those pages here. After writing, call publish_app to build & go live.

Connect a domain the user ALREADY OWNS to a live Kleap app (routing + automatic TLS). The app must be live first — a create_app/modify_app with deployment_status deployed already counts as published, so you do NOT need publish_app first. The user points the domain's A record to Kleap. Does not buy anything.

Use this when the user wants to connect (or reconnect) Google Search Console for a site — typically right after get_search_console reported connected:false. Returns a consent_url: give it to the user as a link and ask them to open it and approve access with the Google account that owns the domain in Search Console. That one approval MUST happen in a browser — Google does not allow it any other way, so never claim you can do it for them. Nothing else is needed afterwards: the Search Console property is bound to the site's custom domain automatically, and get_search_console starts answering. If requires_custom_domain is true the site has no custom domain yet: connecting Google would grant access to nothing, so connect a domain first (connect_domain) and publish. If it reports the site is already connected, do not send anyone through consent again — just read the numbers.

Use this to check whether a website is actually published and live. Returns the published state, the live production URL, and — once a publish has run — the PUBLISH REPORT of what Kleap checked on the site it just built: broken_links (existing pages that fail), dead_nav_links (menu entries pointing at a page that was never written — 90% of real dead links, /contact most often), incoherent_pages (a page answering 200 with content that contradicts the link leading to it), checks (source findings that did NOT block the publish, each with a category and a plain sentence: forms that submit into the void, islands with no client directive so buttons do nothing, broken images, hand-rolled auth or unguarded database access, dead API routes), design_gate (was the rendered homepage looked at), live_verified (was the NEW version confirmed serving), and SEO coverage (JSON-LD pages, sitemap URL count, robots, llms.txt). report.checked:true means the audit RAN, so empty lists mean nothing was found, not that nothing was looked at. If finding_count is above zero, tell the user what was found — in the report's own words, not the rule slugs — and offer to fix it. Do NOT describe a publish as clean when the report lists findings: a site can be live, pretty and still take no leads. status is one of: published, deploying, not_published, unknown_app. Returns the state at THIS instant — report it and end the turn; publishing takes minutes, so calling it repeatedly in one turn only burns the turn.

Use this to take a website LIVE at its public URL. Publishing is VERIFIED-LIVE: the app is only reported published once the new version is provably serving — otherwise it reports 'not confirmed live', never a false 'it is online'. Publishing also AUDITS the built site: every internal link on every page, pages whose content contradicts the link leading to them, and JSON-LD/sitemap/robots coverage. That audit comes back through get_publish_status as `report` — read it before telling the user the launch went well, and offer to fix whatever it lists. Returns immediately. Going live takes minutes, so do NOT poll get_publish_status in a loop inside one turn: tell the user it is publishing, and check once with get_publish_status when they ask again.

Use this when the user asks about traffic, visitors, or which pages/referrers are performing on their PUBLISHED site. Backed by the same analytics as the Kleap dashboard's Visitors view. Returns zeroed data with configured:false if the app has never been published (analytics is set up automatically on publish). Requires the analytics:read scope — sessions connected BEFORE this tool shipped don't have it: on a 403 INSUFFICIENT_SCOPE error, tell the user to disconnect and reconnect the Kleap integration (re-authorize) to grant the scope.

Use this when the user wants to see all their websites with name, slug, preview URL, and production URL.

Use this when the user asks how their site is doing IN GOOGLE SEARCH — keywords/queries they rank for, impressions, clicks from search, CTR, or average position. Backed by their own Google Search Console property (connected per site in Kleap's options), so it is the real Google data, not an estimate. Returns totals plus the top queries and top pages that produced them. Search Console lags real traffic by ~2 days — the newest days are always incomplete, say so rather than reporting a drop. If connected is false or site_selected is false, the site simply has no Search Console hooked up: call connect_search_console(app_id) — it returns a consent_url to hand the user, and that is the whole setup. Do NOT send them hunting through Kleap's settings for it. For visitors and pageviews on the site itself (all sources, not just Google), use get_analytics instead. Requires the analytics:read scope — on a 403 INSUFFICIENT_SCOPE error, tell the user to disconnect and reconnect the Kleap integration (re-authorize).

Use this when the user asks about their remaining credit balance or plan status.

Check a domain's connection / DNS status for a Kleap app.

Search for available domains for a site (e.g. 'mybakery'). Returns available names across TLDs. NOTE: agents cannot buy a domain — purchase is confirmed by the user in Kleap. Use connect_domain for a domain the user already owns.

Change PART of a file without resending it — the counterpart to write_files. Give `old_string` (exact text as in the file today) and `new_string`; Kleap reads, replaces, stores. Nothing else moves. Use it whenever the file exists and only a line, block or URL changes: resending a 30KB layout to fix one line wastes tokens and risks corrupting the rest. read_files first, copy the text EXACTLY. `old_string` must appear once — otherwise the error names the count; add context or pass replace_all:true. Edits are validated together: if any is invalid, nothing is written. Across files the writes are sequential — a late failure names what was already applied. new_string "" deletes the match. Not for new files or binaries. Then publish_app.

Use this when the user asks who filled out their contact form, or wants to see/export leads from their live site. Returns submissions from any <form> built with KleapForm on the app, newest first. Empty list is normal for a brand new site with no visitors yet. Requires the forms:read scope (submissions contain visitor PII) — sessions connected BEFORE this tool shipped don't have it: on a 403 INSUFFICIENT_SCOPE error, tell the user to disconnect and reconnect the Kleap integration (re-authorize) to grant the scope.

Put a REAL photo or illustration on the site by describing it — no image bytes to send. Give a vivid `prompt` and a `public/` `path` (e.g. public/hero.jpg); Kleap generates it with Cloudflare FLUX.2 and stores it as a proper binary asset, exactly like write_files with encoding:"base64" but with NO base64 to transmit (a real image's base64 is too big for a model to emit reliably — this is the ONLY dependable way to add a generated picture). Use it for hero photos, section illustrations, onboarding images, OG images, or to replace a broken/ugly image. Square 768×768 by default; pass width/height (256–1440) for other ratios; hd:true uses the premium model (sharper, slower). ⚠️ To REPLACE an existing image, generate to a NEW filename (e.g. hero-2.jpg) and point the markup at it — overwriting the same path can be served stale from CDN/R2 cache. After it returns, call publish_app to deploy it live.

Use this when the user wants to change or update an existing website. The AI can overwrite or remove existing content and automatically publishes the result to the live site. This consumes Kleap credits. Needs the app_id — if the user named the site by its address (e.g. 'mysite.ch'), call find_app first to get the app_id.

Rename an app's display name. Does NOT change the URL — the live address ({slug}.kleap.io) and any links to it stay intact. (There is no tool to delete the entire app; delete_files removes selected source files.)

Resume a failed or stalled create/modify task from where it stopped — partial files are preserved. Use this when check_task reports 'failed' instead of starting a brand-new create_app. Returns a NEW task_id — poll check_task on that NEW id (not the original). Budget: retry TASK_TIMEOUT/STALE_TASK up to TWICE; retry TASK_FAILED only ONCE; then stop and tell the user. NEVER retry a non-transient error (402 INSUFFICIENT_CREDITS, a rejected prompt).

Use this when the user wants to see a visual screenshot of their website. Rate-limited to 1/min per app. The returned image_url is a PNG on the asset host — render it as an image () and nothing else. It is NOT the website's address, so never present it to the user as their site link, and never open, fetch or web-search it: the site's own address is production_url from get_app / find_app.

Check a create/modify task. Returns quickly with the CURRENT status — report it to the user rather than calling again in the same turn; a build takes 5-15 min, so the answer to 'is it ready?' is usually 'still building, here is the progress'. The optional `wait` can shorten the hold but cannot exceed the server cap (8 seconds by default). status is one of: queued, processing, completed, failed, unknown_task (the id is unknown or aged out — that is an answer, not a failure: check the site itself with get_publish_status). On 'completed' the FILES are written; check deployment_status — 'pending' means the site is going live right now and production_url is still the PREVIOUS version, so say 'built, going live' and check once more in about a minute rather than reporting it stuck. 'deployed' means it is genuinely live. On 'failed': TASK_TIMEOUT/STALE_TASK = transient stall → retry_task (returns a NEW task_id to poll); TASK_FAILED = read error.message, retry once. (Out-of-credits is not a task failure — create/modify reject up front with 402 INSUFFICIENT_CREDITS.)

Use this when the user's website preview is sleeping (sandboxes auto-stop after 15 min). Takes ~30-60s to restart.