![\"Lulu,](\"https://raw.githubusercontent.com/Lulu-The-Narwhal/lulu-ads/master/assets/lulu-ads-hero.jpg\")
\n\n`70% to publishers · CPA only · 800ms fail-open · 0 prompt injections, by design`\n\n[](https://getlulu.dev/api/mcps/sponsor-click/lulu-ads)\n| What the SDK ships (a data field) | \nWhat the host renders (its choice) | \n
|---|---|
| \n\n```json\n{\n \"sponsored\": {\n \"label\": \"Sponsored\",\n \"text\": \"Direct flights TLV–BKK from $412\",\n \"url\": \"https://ads.getlulu.dev/c/9f2a1c\"\n }\n}\n```\n\n | \n\n\n> **Sponsored** — Direct flights TLV–BKK from $412\n> [ads.getlulu.dev/c/9f2a1c](https://ads.getlulu.dev/c/9f2a1c)\n\n | \n
\n![\"Claude\"](\"https://raw.githubusercontent.com/Lulu-The-Narwhal/lulu-ads/master/assets/hosts/claude.svg\")
\n \n![\"ChatGPT\"](\"https://raw.githubusercontent.com/Lulu-The-Narwhal/lulu-ads/master/assets/hosts/openai.png\")
\n \n![\"CopilotKit\"](\"https://raw.githubusercontent.com/Lulu-The-Narwhal/lulu-ads/master/assets/hosts/copilotkit.png\")
\n \n![\"VS](\"https://raw.githubusercontent.com/Lulu-The-Narwhal/lulu-ads/master/assets/hosts/vscode.png\")
\n \n![\"Cursor\"](\"https://raw.githubusercontent.com/Lulu-The-Narwhal/lulu-ads/master/assets/hosts/cursor.svg\")
\n \n![\"Goose\"](\"https://raw.githubusercontent.com/Lulu-The-Narwhal/lulu-ads/master/assets/hosts/goose.png\")
\n \n![\"Grok](\"https://raw.githubusercontent.com/Lulu-The-Narwhal/lulu-ads/master/assets/hosts/xai-grok.png\")
\n \n![\"Windsurf\"](\"https://raw.githubusercontent.com/Lulu-The-Narwhal/lulu-ads/master/assets/hosts/windsurf.svg\")
\n \n![\"Cline\"](\"https://raw.githubusercontent.com/Lulu-The-Narwhal/lulu-ads/master/assets/hosts/cline.svg\")
\n \n![\"Zed\"](\"https://raw.githubusercontent.com/Lulu-The-Narwhal/lulu-ads/master/assets/hosts/zedindustries.svg\")
\n
![](\"https://your-cdn.com/logo.png\"){kind=logo}
` gets silently dropped — no\nerror anywhere, the card just renders with a blank slot forever, in every\nhost. `data:` URIs are always allowed under that same rule, so fetching and\ninlining server-side sidesteps the whole failure mode — there is no CSP\nconfig for you to get right or forget.\n\nA bad or unreachable `logo` never breaks registration — it's skipped (with\na warning log) and the card renders without one, same as leaving `logo`\nunset. Only `image/png`, `image/jpeg`, `image/svg+xml`, `image/webp`, and\n`image/gif` are accepted, capped at 200KB (the logo renders at 28×28 in the\ncard — there's no reason to ship more than that over the wire).\n\n## CLI rendering\n\nTerminals have no widget surface — the model's own text is the only\noutput there is, and it's genuinely the model's judgment call whether to\nmention the disclosed line at all (never forced, ever — see Guarantees).\n`LuluAdsMiddleware` / `withLuluAds` detect known CLI clients via the MCP\n`clientInfo.name` sent at `initialize` (currently: `claude-code`, verified\nlive) and, when connected from one, append a bordered plain-text card to\n`content[]` in addition to the plain field — still just data, still zero\ninstruction to the model, just formatted so it reads as a distinct block\ninstead of a plain sentence if the model does choose to relay it:\n\n```\n╭─ Sponsored ────────────────────────────────────╮\n│ Search 700+ airlines in one place — Kiwi.com │\n│ finds routes other search engines miss. │\n╰─ via Lulu Ads ─────────────────────────────────╯\n→ https://ads.getlulu.dev/c/9f2a1c\n```\n\nKnown limitation, disclosed here rather than glossed over: some MCP\nclients don't forward every `content[]` block to the model when\n`structuredContent` is also present on the same result — an open\nclient-side bug in Claude Code, twice reported and twice closed without a\nfix ([#55677](https://github.com/anthropics/claude-code/issues/55677) →\nconsolidated into\n[#45575](https://github.com/anthropics/claude-code/issues/45575) →\nauto-closed stale). Live-tested against Claude Code specifically\n(2026-07-21): with `structuredContent` present (the shipped default), the\nboxed card never reaches the model, but the plain `sponsored` field still\ndoes — the model reliably surfaces it as an honest, labeled\n\"Sponsored: ...\" line in its own words, 3/3 runs, no issues.\n\n### `cliTextMode` — opt-in fix for the client bug above\n\nWe also tested the obvious-looking fix — omit `structuredContent` so\n`content[]` has nothing competing with it — and the result depended\nentirely on what else was in `content[]`:\n\n- Ad **alone**, no real tool data alongside it: the card arrives every\n time, but the model flags it as a suspected prompt-injection attempt\n and warns the user off it, 3/3 runs. Worse than not showing it.\n- Ad **alongside a real, complete rendering of the tool's own result**:\n the card arrives every time, the model treats it as an ordinary\n disclosed ad and mentions it neutrally, 3/3 runs. No suspicion.\n\nSo the fix is real, but conditional on your tool's own behavior — which\nthis SDK can't verify for you, hence opt-in, off by default:\n\n```python\nmcp.add_middleware(LuluAdsMiddleware(cli_text_mode=True))\n```\n\n```typescript\nwithLuluAds(server, ads, { cliTextMode: true });\n```\n\nTurn this on only if your tool's `content[]` already contains a\ncomplete, human-readable rendering of the result on its own — not a\nplaceholder like \"see structuredContent\". When on, detected CLI clients\nwith no declared `outputSchema` get `structuredContent` stripped so\n`content[]` (your tool's own text + our card) reliably reaches the\nmodel. Tools that declare an `outputSchema` are never touched by this —\nstripping `structuredContent` there would break client-side schema\nvalidation outright (confirmed: `fastmcp.exceptions.ToolError`\n\"outputSchema defined but no structured output returned\"), which is a\nbroken tool call, a strictly worse outcome than a dropped card. This SDK\nnever drops `structuredContent.sponsored` on schema'd tools to chase card\nvisibility, `cliTextMode` or not.\n\nUntil the upstream client bug is fixed, treat the CLI card as \"renders\nreliably once you opt in and your tool qualifies, on top of a disclosure\nthat already works either way\" — same verify-in-your-own-host caveat as\nthe widget path above.\n\n## stdio servers\n\nEverything above the \"Widget rendering\" section works unmodified on a\nstdio-transport server — the SDK is a library your code imports and calls;\nit doesn't know or care how your own server talks to *its* clients. The\nplain `sponsored` data field (`LuluAdsMiddleware` / `mcp.add_middleware()`,\n`withLuluAds(server)`) takes no endpoint argument and makes a plain\noutbound HTTPS call to `ads.getlulu.dev/slot` — same request whether your\nprocess is a long-running remote server or a `npx`/`uvx`-launched local\none. The CLI text-card path (see \"CLI rendering\" above) is the common\nreal-world case here: Claude Code launches most of its MCP servers over\nstdio, and that's exactly the client this SDK already detects and renders\na disclosed plain-text card for.\n\nThe rendered **MCP Apps widget is the one piece that doesn't apply** —\n`enable_lulu_ads`/`enableLuluAds` and the lower-level\n`register_sponsored_widget`/`registerSponsoredWidget` all require a real\n`endpoint_url`, hashed into Claude's undocumented `_meta.ui.domain` value\nfor the widget's iframe CSP. That's not a Lulu Ads limit; MCP Apps'\n`ui/initialize` handshake is a network protocol between the host and your\nserver's own HTTP endpoint, and a stdio server has none. If your server is\nstdio-only, call `LuluAdsMiddleware`/`mcp.add_middleware()` directly (or\n`withLuluAds(server)` in TypeScript) — never `enable_lulu_ads` — and you\nget the data field plus the CLI text-card, with nothing to configure for\nthe endpoint you don't have.\n\nPublisher-side note: the marketplace's automatic \"monetized\" badge\ncurrently matches a listing to your registered publisher account by\n`remote_url` — a stdio listing has none, so it won't auto-badge even once\nyou've integrated the SDK and are earning. The SDK/earnings path itself is\nunaffected; this is purely a marketplace-listing display gap, being\ntracked separately.\n\n## Guarantees (enforced in code, not just promised)\n\n| Guarantee | How |\n|---|---|\n| A tool call can never break because of ads | every failure path returns `None`/`null`; hard 800ms wall-clock timeout (3000ms when the call implies server-side classification) |\n| Always disclosed | `label: \"Sponsored\"` is set by the SDK, never sourced from the response body |\n| No prompt injection, ever | we ship a data field; there is no display instruction anywhere in the contract |\n| No PII leaves your server | `context` is filtered against an allowlist client-side, before any request is built |\n| Quality-gated | every creative passes [Dali](https://dali.getlulu.dev) scoring (≥70) before it can fill a slot |\n| Intent, not identity | targeting uses this call's stated context only — no user profiles, no cross-session ID |\n| Misconfigured? Still safe | missing credentials → client is inert, returns `None`/`null`, zero network calls |\n\n## Why not just…\n\n**…tell the model to mention a sponsor in its reply?**\nDisplay instructions get MCP servers delisted by registries that scan for\ninjected directives. We ship a plain data object — `label`, `text`, `url` —\nwith no field, anywhere in the contract, that tells a model how to render or\nphrase anything.\n\n**…count impressions and charge per view?**\nAn \"impression\" only exists if a model actually rendered it, and that's\nunverifiable from the server side — easy to game, hard to audit. We charge\nCPA only, on a click that redeems a signed, server-verified token. Payment\nmaps to a real user action, not a claim.\n\n**…scan the conversation to target better?**\nReading transcripts to target ads is a privacy trap: everything a user says\nbecomes ad-targeting data. We accept six allowlisted context keys — `tool`,\n`category`, `query`, `route`, `locale`, `country` — stated intent for this\ncall only. No transcripts, no profiles, no PII fields exist in the schema.\n\n## How it works\n\n```\ntool call\n │\n ▼\nyour tool's own result\n │\n ▼\nPOST /slot (1500ms cap — 3000ms when classifying a raw prompt — allowlisted context only)\n │\n ▼\nlabeled data field { label: \"Sponsored\", text, url } ← attached, never injected\n │\n ▼\nhost / model judgment → renders it, or doesn't — not our call\n │ user clicks\n ▼\nGET /c/{token} → signed redirect, click recorded\n │\n ▼\nadvertiser's affiliate rails → POST /postback on conversion\n │\n ▼\n70% publisher / 30% Lulu, on the ledger. Earnings accrue to your balance from the first audited conversion — cash out from $100.\n```\n\nFull wire-level detail: [`docs/contract.md`](docs/contract.md).\n\n---\n\nDocs: https://getlulu.dev/docs · [Quickstart](docs/quickstart.md) ·\n[API contract](docs/contract.md) · [Integrations](docs/integrations.md) ·\n[Publisher signup](https://getlulu.dev/publishers) · Quality gate:\n[Dali](https://dali.getlulu.dev) · [MIT](LICENSE)\n\n## Changelog\n\n- **0.9.6** — Docs only: new [Supported surfaces](docs/supported-surfaces.md)\n page sorting every agent surface (chat hosts, agentic SDKs/frameworks,\n response-suffix runtimes, AI app builders, MCP hosting/registries) by how\n it actually reaches the SDK — a direct adapter, MCP protocol passthrough\n (no adapter needed once a server has Lulu Ads wired in), the generic\n `format_suffix` contract, or genuinely not yet evaluated — same\n evidentiary bar as the rest of this repo. Also adds a \"stdio servers\"\n section clarifying the data-field path needs no `endpoint_url` and works\n unmodified on stdio-transport servers; only the rendered MCP Apps widget\n requires one and can't apply to stdio. Also fixes `lulu_ads.__version__`,\n which had drifted to 0.9.0 while the package published as 0.9.5 — same\n class of bug as the 0.7.0 entry below, recurred because nothing enforces\n the two staying in sync; consider that the next real gap to close here.\n- **0.9.2** (Python only) — Fixed a middleware bug: a tool that sets its\n own `sponsored` field (a documented pattern for e.g. a category-specific\n cross-sell) triggered the \"never overwrite\" early return in\n `on_call_tool` before the CLI-client check ran, so CLI hosts (Claude\n Code) got no visible ad at all on that tool — no widget surface, and no\n text-card safety net either, both skipped by the same early exit. The\n client check now runs first; a pre-set `sponsored` value still gets the\n CLI text-card treatment, using the tool's own chosen ad.\n- **0.9.1** — `table-card` widget gains `rowLink`: an optional per-row\n dot-path resolving to a URL (e.g. a booking/checkout link), wired to\n the same host-agnostic `openLink()` the sponsored strip already uses.\n Rows without a resolvable URL render exactly as before.\n- **0.9.0** — Skybridge (https://skybridge.tech) support:\n `withLuluAdsSkybridge(server)` (`lulu-ads/skybridge`). Skybridge's\n `McpServer.registerTool` takes a 2-arg `(config, handler)` shape with\n `name` folded into `config`, not the official SDK's 3-arg\n `(name, config, handler)` that `withLuluAds` wraps — reusing `withLuluAds`\n as-is would misread the config object as the tool name. The new adapter\n instead uses Skybridge's own `mcpMiddleware(\"tools/call\", ...)` protocol\n hook, verified against the real `skybridge@1.4.0` package's shipped types\n and a live `InMemoryTransport` round-trip. Deliberately `_meta`-only:\n the middleware sees the call result but not the tool's registered\n `outputSchema`, so `structuredContent` is never touched.\n- **0.8.1** — Result-widget template gallery (supersedes 0.8.0, which\n briefly shipped on npm with a louder strip design): `lulu_ads.widgets` /\n `lulu-ads/widgets` with four predefined templates (`stat-card`,\n `table-card`, `notice-card`, `carousel-card`), design tokens + `.lw-*`\n primitives, and the disclosed SPONSORED strip built into the frame\n (advertiser logo via the slot's new `logo_url`, letter-tile fallback).\n `register_result_widget()` patches an already-registered FastMCP tool in\n place (or returns the AppConfig for explicit `app=`).\n\n- **0.7.4** — Widget: the sponsored card's iframe canvas no longer paints\n an opaque white box on dark hosts. `background: transparent` alone is\n not enough for an embedded iframe: Chromium keeps the canvas\n transparent only when the embedded document's used color scheme matches\n the embedder's, and this document declared none (defaulting to\n `light`), so dark-themed hosts (e.g. claude.ai in dark mode) forced a\n white backdrop behind the card. The widget now declares\n `color-scheme: light dark`, which resolves to the user's preferred\n scheme — matching hosts that follow it (claude.ai does by default) on\n both light and dark themes. Verified empirically against light- and\n dark-scheme embedding pages. (Also aligns `lulu_ads.__version__`, which\n had drifted to 0.7.2 while the packages published as 0.7.3.)\n\n- **0.7.0** — Two real bugs, found live against a real third-party MCP\n server behind Claude.ai's remote connector, both fixed:\n - **0% ad delivery on hosts that reconnect per message** (confirmed:\n Claude.ai opens a brand-new MCP session per chat message, not once per\n conversation). Root cause: this SDK's persistent HTTP connection goes\n cold on any real idle gap between messages, but only a one-time\n \"have I ever succeeded\" check protected the very first call ever —\n every later cold call still got the tight steady-state timeout and\n failed. Fixed by re-checking coldness on every call, keyed to time\n since the last real success, not a permanent latch. Also: the fast\n steady-state timeout itself was raised 800ms → 1500ms\n (Python and TS) — production evidence showed even \"warm\" calls\n sometimes measuring 796-802ms, right at the old line rather than\n comfortably under it.\n - **Ad fetched successfully, never seen by the model.** FastMCP/the\n MCP TS SDK build a tool result's `content[]` once, from the tool's\n original return value, before `LuluAdsMiddleware`/`withLuluAds` ever\n run — mutating `structuredContent` alone (the only thing this SDK's\n own test suite checked) left `content[]` permanently stale. Confirmed\n live: the wire response's `structuredContent` demonstrably had\n `sponsored`, but Claude.ai read and reported back from `content[]`,\n which didn't. Both SDKs now keep `content[]` in sync whenever it's\n safe to (a single auto-generated JSON text block); regression tests\n added for the exact gap that let this ship unnoticed the first time.\n - **New:** `enable_lulu_ads()` (Python) / `enableLuluAds()` (TS) — one\n call that wires both the data field AND the rendered MCP Apps widget\n onto every tool automatically, present and future. Existing\n `register_sponsored_widget()`/`registerSponsoredWidget()` +\n `app=`/`_meta.ui` per tool still works and is now documented as the\n lower-level building block for per-tool control; the gap it left (an\n easy-to-forget manual step per tool) is exactly what this closes —\n found live on our own dogfood server, which had wired the widget onto\n exactly one tool by hand and silently never updated it for tools\n added since.\n- **0.6.2** — The sponsored card now plays a one-time diagonal light sweep\n across itself when it settles into the loaded state (a real ad won) —\n pure CSS (`.card-shine` in `js/widget-src/src/index.css`), fires exactly\n once per mount (not a looping shimmer, since this sits inline in a real\n chat thread), and respects `prefers-reduced-motion`. Skeleton and\n no-fill states are unaffected.\n- **0.6.1** — Corrects a stale `0.6.0` published to npm before `dist/` was\n rebuilt from the merged source (`js/` has no `prepublishOnly` build\n step) — 0.6.0 is deprecated on npm pointing here. Also fixes README.md\n and both languages' `widget.py`/`widget.ts` docstrings, which\n incorrectly claimed `text`/`url`/`logo` passed to\n `register_sponsored_widget()` render as a fallback \"house ad\" until a\n live `tool-result` arrives; they never do — the widget shows the\n skeleton indefinitely if a host never pushes it.\n- **0.6.0** — The MCP Apps sponsored widget now shows **live, per-call ad\n content** instead of a fixed house ad baked in at registration time:\n rebuilt in React + shadcn/ui (`Card`, `Skeleton`, `Button`), compiled to\n a single self-contained bundle shared byte-for-byte by both SDKs\n (`js/widget-src/`). The widget shows a skeleton immediately on load,\n then listens for the MCP Apps host's own `ui/notifications/tool-result`\n push — which the spec already delivers once per call, to a fresh iframe\n per call, with no server-side change needed — and swaps to that call's\n real `structuredContent.sponsored` data — the widget shows the skeleton\n indefinitely if a host never pushes it, not a fallback ad; only\n `label`/`cta`/`accent*` from `register_sponsored_widget()`/\n `registerSponsoredWidget()`'s options are actually used by the live\n path. The \"Powered by Lulu Ads\" footer renders once, immediately, and\n is never itself part of the skeleton→card swap. Live-verified against a\n real host (claude.ai) with a throwaway test server: skeleton renders\n before the tool call resolves, swaps to the real per-call card once it\n does, the footer never disappears or reflows during the swap, and two\n tool calls in the same turn render two fully independent widget\n instances, each showing only its own call's data — confirming the \"per\n call, not per tool\" behavior this feature is built on. (The CTA's\n `ui/open-link` redirect — vs. a raw navigation — was re-confirmed by\n static code inspection and this repo's existing unit tests during this\n same pass; live click-through capture was attempted but blocked by\n browser-automation tooling limits reaching inside the host's\n double-sandboxed iframe, not by any observed product failure.)\n- **0.4.0** — Automatic pre-connect on construction for LangChain's\n `LuluAdsAgentMiddleware`, CrewAI's `install()`, and TypeScript's\n `withLuluAds` (matching the FastMCP `LuluAdsMiddleware`, which already\n had this). Also: FastMCP's `LuluAdsMiddleware` and LangChain's\n `LuluAdsAgentMiddleware` now additionally warm the **async** connection\n pool their `await`ed `sponsored_slot()` traffic actually uses — the\n construction-time warm-up above only ever touched the sync client, a\n separate pool the async path never touches. `LuluAds.async_warm_up()`\n is fired once per instance from a real framework lifecycle hook on the\n live serving event loop (FastMCP's `on_initialize`, LangChain's\n `abefore_agent`), since a background thread can't safely pre-warm a\n connection meant for a different event loop. Gated by the same\n `auto_warm_up` flag as the sync warm-up (this async path is Python-only —\n TypeScript's `autoWarmUp` only ever had one pool to gate). This is the fix\n that closes the cold-start gap for `dali-mcp` in production, which\n consumes the async path. Short-TTL (default 45s) success-only cache in\n both base clients, keyed on resolved category or a hash of the prompt\n text. Corrected documentation: the real default timeout is 800ms (fast\n path) / 3000ms (classify path) adaptive, not a flat 300ms.\n- **0.3.7** — `cliTextMode` (opt-in, off by default): fixes the Claude Code\n content[]-drop bug for real, but only for tools whose `content[]` already\n stands on its own without `structuredContent` — live-tested both\n qualifying and non-qualifying cases, see \"CLI rendering\". Never touches\n tools with a declared `outputSchema` (would break client-side schema\n validation, confirmed via `fastmcp.exceptions.ToolError`).\n- **0.3.6** — automatic connection warm-up on `LuluAdsMiddleware` construction\n (`auto_warm_up`, on by default): a genuinely cold first tool call measured\n 804ms against the 800ms fast-path default — right at the ceiling, not\n under it. `LuluAds` itself still never auto-warms (a network call as a\n constructor side effect is surprising in a general-purpose client), but\n the middleware is the \"one line, zero config\" promise, so it warms itself.\n- **0.3.5** — fixed a hardcoded 300ms default `timeout_ms` on\n `LuluAdsMiddleware` that silently dropped real, fillable ads on real\n network latency — every test in the suite used an instant mock transport,\n which is exactly why this shipped unnoticed. Default is now `None`,\n deferring to `LuluAds`'s own conditional 800ms/3000ms default.\n- **0.3.4** — CLI card gets rounded corners and a \"via Lulu Ads\" footer\n (Unicode box-drawing only — a live test against Claude Code confirmed it\n strips raw ANSI color escapes from tool output before the model sees\n them, so color was never on the table). Also live-tested and explicitly\n rejected dropping `structuredContent` to force `content[]` through: it\n does make the card arrive, but the model then flags it as suspected\n prompt injection and warns the user off it — worse than the status quo,\n where the plain field still gets surfaced honestly even without the\n card. See \"CLI rendering\" for the full writeup.\n- **0.3.3** — CLI-adaptive rendering: `LuluAdsMiddleware` / `withLuluAds` detect\n known CLI clients via the MCP `clientInfo.name` sent at `initialize`\n (currently: `claude-code`, verified live) and append a bordered plain-text\n card to `content[]` for them, in addition to the plain field — terminals\n have no widget surface, so this is the CLI-safe equivalent of the MCP Apps\n widget above. Still just data; see \"CLI rendering\" for the disclosed known\n limitation on some clients' `content[]` forwarding.\n- **0.3.0** — `register_sponsored_widget()` / `registerSponsoredWidget()` gain\n a `logo` option: fetched server-side at registration time and inlined into\n the widget as a `data:` URI, so it renders under the widget sandbox's CSP\n (`img-src 'self' data: