![\"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.19** — **Fixes what the SDK reported about itself.**\n\n `SDK_VERSION` in the TypeScript client was a hardcoded `\"0.9.14\"` while the\n package moved through four releases — and it is *sent* to `/slot` as\n `sdk_version`, so every TypeScript publisher reported 0.9.14 and upgrade\n telemetry could not tell who had actually upgraded. Now correct, and pinned\n by a test against `package.json` so a release that forgets it fails the suite\n instead of quietly corrupting the data. The Python client never had this bug;\n it imports `lulu_ads.__version__`.\n\n Docs, no behaviour change: `js/src/skybridge.ts`'s header still described the\n adapter as `_meta`-only, which stopped being true in 0.9.15 — it now carries\n the same four-case landing table as `docs/integrations.md`. And\n `python/README.md`, which is what PyPI renders, had no sync with the root\n README and had fallen four releases behind, so the package page described\n Skybridge using that same retired claim. Both package READMEs are now fed by\n `scripts/sync-readmes.sh`.\n\n- **0.9.18** — **Skybridge 2.x support, and a guard against its one silent\n failure.**\n\n skybridge 2.x moved protocol-middleware wiring out of\n `McpServer.connect()` into the app's request path, so the attach point\n differs by major:\n\n ```ts\n // 2.x — inside the app handler\n new Skybridge({ name, version, handler: (server) => {\n withLuluAdsSkybridge(server);\n return server.registerTool({ name: \"t\" }, handler);\n }});\n\n // 1.x — on the server you connect yourself\n withLuluAdsSkybridge(server);\n ```\n\n Using the 1.x shape on 2.x registers the middleware into a chain nothing\n applies: no error, no ad, nothing to debug. The adapter now detects that\n (its middleware always runs before a tool handler, so a tool executing\n while it never ran means it isn't wired) and **warns once** with the\n correct snippet. Warned, never thrown.\n\n Verified against both majors — 106/106 on `skybridge@1.4.1` and `@2.0.0`,\n plus an end-to-end example run against the published package. Note that on\n 2.x an idiomatic `content`-only tool carries the ad on `_meta` alone, so a\n view should read `structuredContent` first and fall back to `_meta`; the\n reference view in `examples/skybridge-views/` does exactly that.\n\n- **0.9.15–0.9.17** — **Skybridge delivers at all, and the SDK reports who is\n calling.**\n\n > **On 2.0.1:** these changes were briefly published as `2.0.1` before being\n > retired — the major stranded every existing `^0.9.x` dependency range,\n > which meant nobody would have received them without hand-editing their\n > package.json. It is yanked on PyPI and superseded on npm; use the 0.9.x\n > line. Nothing was lost, only renumbered.\n\n *Skybridge.* `withLuluAdsSkybridge` used to\n attach `sponsored` to `_meta` only. Nothing on the Skybridge path reads\n `_meta` — `enableLuluAds` can't register a widget there (Skybridge's\n `registerViewResource` is private) and there's no CLI card — so the slot\n was fetched, logged, and surfaced to nobody. Probing the live result\n shape showed `content[]` arrives **empty** on Skybridge with\n `structuredContent` populated (the inverse of the official SDK), so\n `structuredContent` is what a view renders from. It now lands there:\n\n | tool shape | `sponsored` goes to |\n |---|---|\n | no `outputSchema` | `structuredContent` **and** `_meta` |\n | has `outputSchema` | `_meta` only — an unlisted field would fail the client's validation |\n | registered before `withLuluAdsSkybridge` | `_meta` only — schema status unknown, safe default |\n\n The schema flag is captured at registration time via a 2-arg\n `registerTool` wrapper, since `mcpMiddleware` can't see `outputSchema`.\n\n *Client identity.* Every adapter now forwards the MCP client name as\n `context.client`, so ads-server can tell a real agent from a directory\n crawler. `\"client\"` joins the context allowlist. No integrator code\n changes.\n\n *Two silent breakages fixed on fastmcp 4.x / MCP SDK v2.* `clientInfo`\n was renamed `client_info`; the old spelling raised inside a bare\n `except`, so `_connected_client_name` returned `None` on every 4.x host\n — which also silently disabled the **CLI sponsored card**\n (`is_cli_client(None)` is False). And 4.x negotiates `server/discover`\n instead of `initialize`, so `on_initialize` never fired and the async\n warm-up stopped, handing back the cold-start latency the tiered-timeout\n work exists to avoid. Both accessors now try new-then-old spellings, and\n `on_discover` runs alongside `on_initialize`. Python suite: 144 passed /\n 0 failed on **both** 4.0.5 and 3.4.4 (was 8 failing). JS: 104/104.\n\n *Upgrading:* staying on the 0.9.x line is deliberate — a `^0.9.x` range\n reaches 0.9.18, so `npm update lulu-ads` / `pip install -U lulu-ads` is\n enough and no dependency range needs editing. That propagation is exactly\n what the retired 2.0.1 would have cost.\n\n See [`examples/skybridge_server.ts`](examples/skybridge_server.ts) and\n `npm run verify:skybridge`, which asserts all of the above against a\n real server over an in-memory transport.\n\n- **0.9.14** — An ad's per-call `template` (LUL-64, when `/slot` reports one)\n now wins over the `template=`/`template:` you registered with, for the\n standalone sponsor-card widget (`register_sponsored_widget()`/\n `registerSponsoredWidget()`). If it's absent or not a template this\n bundle build recognizes, it falls back to your registration-time\n default as before, then to `\"card\"`. **Behavior change on upgrade, no\n code change required:** if you registered with a non-default\n `template=` (e.g. `\"hero\"`), ads that carry their own live template\n will now render in that template instead, with no opt-out. This is\n intentional — an admin picking a template for a specific ad is meant to\n be more specific than a blanket integrator default — but it does mean\n your widget's visual output can change after upgrading even though you\n changed no code. Also fixes a lookup hazard where a prototype-chain\n name (e.g. `\"constructor\"`) in a live `template` value could be\n misread as \"recognized\" and crash the render after the impression\n beacon had already fired.\n- **0.9.13** — Fixed a rendered-impression billing gap (LUL-71) in the\n standalone sponsor-card widget (`register_sponsored_widget()`/\n `registerSponsoredWidget()` — the React-built card, banner, flip-card,\n scratch-reveal, spin, and hero templates): the wire payload's `imp_url`/\n `impUrl` field was parsed and exposed by both clients (`Sponsored.impUrl`\n in the Node SDK, `imp_url` in the Python client) but silently dropped by\n the widget bundle's own message parsing before it ever reached the\n React components — so the rendered-impression beacon (a 1px `