krawlup MCP documentation

Introduction

krawlup runs a Model Context Protocol server over streamable HTTP. It is stateless: no session id is required, and responses are plain JSON. Once connected, an agent reads your products' scores, the failing audits behind them, AI fix cards, first-party analytics and keyword ideas. With extra scopes it can also start full rescans, add products from a URL, and publish them to the public directory, while every payment stays in your browser.

Connect your agent

One endpoint, every client. Where a client supports both paths, the OAuth flow needs no key at all; an agent key works everywhere and is the only credential that can carry rescan. A browser-approved connection gets read + submit and never rescan; denying returns the agent to its redirect with error=access_denied. Connections and keys are both managed on the AI agent page.

Claude Code Cursor Codex Claude app ZCode Command Code OpenCode Copilot Any agent

Claude Code connects over streamable HTTP with one command; the browser handles the approval.

OAuth recommendedAgent key

1. 1Run this in your project root.
2. 2When the agent first needs krawlup it opens your browser; approve while signed in.
3. 3The connection sticks. Manage or remove it on the Dashboard → AI agent page.

Terminal Copy

claude mcp add --transport http krawlup https://api.krawlup.com/mcp

Windsurf, Zed and VS Code accept the same mcpServers JSON shape as Cursor. Scopes, limits and every tool: krawlup.com/docs.

Agent skills

Instead of (or alongside) MCP, teach your agent krawlup directly. The official @krawlup/skills package installs two plain-markdown skills: krawlup-mcp (all 20 tools, scopes and rate limits) and krawlup-analytics-setup (installing the cookieless tag and wiring conversion goals). No code, just instructions your agent reads.

npx @krawlup/skills

Skills land in ./skills by default. Point --dir at your agent's skills folder (for example --dir .claude/skills) and use --force to overwrite an older copy.

Authentication and scopes

Scopes

Agents see only their own products. Revoking a key or disconnecting a connection stops the agent on its very next request.

Tool reference

20 tools. Every call is throttled to 60 requests per minute per credential unless a tighter limit is shown. Limits shown in orange differ from that blanket.

REST API

The same agent key authenticates a small REST twin under /agent/v1, for scripts that do not speak MCP. Scope, budget and gating rules match the MCP tools 1:1.

curl -H "Authorization: Bearer sk_ag_YOUR_KEY" \
  https://api.krawlup.com/agent/v1/products

Install the analytics tag

krawlup's first-party analytics is 3,287 bytes parsed, 1,383 bytes gzipped and 100% cookieless: pageviews on load and on SPA route changes, custom conversion goals, checkout attribution, and it honors Do Not Track. Every product gets its own token on the Dashboard → products → Website tab, or your agent can fetch it with the get_analytics_snippet MCP tool.

Zero dependencies (HTML tag)

Prefer no package? Paste this in the <head> of your website or template:

<script>window.krawlup=window.krawlup||function(){(window.krawlup.q=window.krawlup.q||[]).push(arguments)};</script>
<script defer src="https://krawlup.com/t.js" data-site="YOUR_ANALYTICS_TOKEN"></script>

Data appears in your Website tab within 60 seconds of the first visit. The script loads asynchronously without blocking DOM rendering or Core Web Vitals.

As a library (NPM)

For Next.js, Nuxt, React, Vue, SvelteKit, and Astro projects, install the official @krawlup/analytics-tag package:

npm i @krawlup/analytics-tag

import { injectKrawlup, trackEvent } from '@krawlup/analytics-tag'

// once, client-side, in your app entry
injectKrawlup({ site: 'YOUR_ANALYTICS_TOKEN' })

// custom conversion goals anywhere; safe to call before the tag loads
trackEvent('purchase', { value: 49.0, currency: 'USD' })

WordPress & WooCommerce

Using WordPress or WooCommerce? The WordPress & WooCommerce plugin is coming soon. Until then, connect via the HTML script tag:

Shopify (Custom Web Pixel)

Running a Shopify store? Connect via Shopify's native Customer Events custom pixel with zero app installation and zero code modifications:

// Shopify Admin -> Settings -> Customer Events -> Add custom pixel
const SITE_TOKEN = "YOUR_ANALYTICS_TOKEN";
const ENDPOINT = "https://api.krawlup.com/t/hit";

function send(event, t, n, d) {
  const doc = event?.context?.document || init?.context?.document;
  const p = {
    k: SITE_TOKEN,
    t: t,
    h: doc?.location?.host || "",
    p: doc?.location?.pathname || "/",
    r: doc?.referrer || "",
    n: n,
    d: d
  };
  fetch(ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "text/plain" },
    body: JSON.stringify(p),
    keepalive: true
  }).catch(() => {});
}

analytics.subscribe("page_viewed", (event) => send(event, "pageview"));
analytics.subscribe("checkout_completed", (event) => {
  const c = event.data?.checkout;
  if (!c) return;
  send(event, "event", "purchase", {
    value: parseFloat(c.totalPrice?.amount || 0),
    currency: c.totalPrice?.currencyCode || "USD",
    order_id: c.order?.id || c.token || ""
  });
});

Limits and budgets

• Free site report reads are unlimited; scans are not: get_site_report is a cached read with no cost, while run_site_report spends one of the same two full scans per calendar month the /site-report website gives you — counted per agent credential (or per IP when anonymous), in a budget separate from browser visitors.
• 60 requests/minute per credential across all tools; tighter per-tool limits are shown in the tool tables.
• Reads are free and unlimited within the rate limit — no read consumes plan allowances. Some reads are facility-gated exactly like the dashboard: fix cards need the ai_fix_cards facility and keyword ideas the keyword_research facility; conversion events and the stored AI insight arrive only when the plan carries theirs.
• Rescans spend plan allowances: one full analysis plus one page-speed check per billing period, exactly like the dashboard button.
• Publishing is paid-only: set_product_public works on an active paid subscription; trial users must upgrade first. The agent never pays for anything.
• Analytics needs a subscription: get_analytics_snippet and get_website_analytics answer only while the subscription is active or inside the 3-day renewal grace window.

Related

Something missing? Tell us. Machine-readable summaries live at /llms.txt and /llms-full.txt. Official packages @krawlup/skills and @krawlup/analytics-tag are on npm, with platform integrations for WordPress (Coming Soon) and Shopify.