`70% to publishers ยท CPA only ยท 800ms fail-open ยท 0 prompt injections, by design`
[](https://getlulu.dev/api/mcps/sponsor-click/lulu-ads)
| What the SDK ships (a data field) | What the host renders (its choice) |
|---|---|
| ```json { "sponsored": { "label": "Sponsored", "text": "Direct flights TLVโBKK from $412", "url": "https://ads.getlulu.dev/c/9f2a1c" } } ``` | > **Sponsored** โ Direct flights TLVโBKK from $412 > [ads.getlulu.dev/c/9f2a1c](https://ads.getlulu.dev/c/9f2a1c) |
` gets silently dropped โ no
error anywhere, the card just renders with a blank slot forever, in every
host. `data:` URIs are always allowed under that same rule, so fetching and
inlining server-side sidesteps the whole failure mode โ there is no CSP
config for you to get right or forget.
A bad or unreachable `logo` never breaks registration โ it's skipped (with
a warning log) and the card renders without one, same as leaving `logo`
unset. Only `image/png`, `image/jpeg`, `image/svg+xml`, `image/webp`, and
`image/gif` are accepted, capped at 200KB (the logo renders at 28ร28 in the
card โ there's no reason to ship more than that over the wire).
## CLI rendering
Terminals have no widget surface โ the model's own text is the only
output there is, and it's genuinely the model's judgment call whether to
mention the disclosed line at all (never forced, ever โ see Guarantees).
`LuluAdsMiddleware` / `withLuluAds` detect known CLI clients via the MCP
`clientInfo.name` sent at `initialize` (currently: `claude-code`, verified
live) and, when connected from one, append a bordered plain-text card to
`content[]` in addition to the plain field โ still just data, still zero
instruction to the model, just formatted so it reads as a distinct block
instead of a plain sentence if the model does choose to relay it:
```
โญโ Sponsored โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ Search 700+ airlines in one place โ Kiwi.com โ
โ finds routes other search engines miss. โ
โฐโ via Lulu Ads โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
โ https://ads.getlulu.dev/c/9f2a1c
```
Known limitation, disclosed here rather than glossed over: some MCP
clients don't forward every `content[]` block to the model when
`structuredContent` is also present on the same result โ an open
client-side bug in Claude Code, twice reported and twice closed without a
fix ([#55677](https://github.com/anthropics/claude-code/issues/55677) โ
consolidated into
[#45575](https://github.com/anthropics/claude-code/issues/45575) โ
auto-closed stale). Live-tested against Claude Code specifically
(2026-07-21): with `structuredContent` present (the shipped default), the
boxed card never reaches the model, but the plain `sponsored` field still
does โ the model reliably surfaces it as an honest, labeled
"Sponsored: ..." line in its own words, 3/3 runs, no issues.
### `cliTextMode` โ opt-in fix for the client bug above
We also tested the obvious-looking fix โ omit `structuredContent` so
`content[]` has nothing competing with it โ and the result depended
entirely on what else was in `content[]`:
- Ad **alone**, no real tool data alongside it: the card arrives every
time, but the model flags it as a suspected prompt-injection attempt
and warns the user off it, 3/3 runs. Worse than not showing it.
- Ad **alongside a real, complete rendering of the tool's own result**:
the card arrives every time, the model treats it as an ordinary
disclosed ad and mentions it neutrally, 3/3 runs. No suspicion.
So the fix is real, but conditional on your tool's own behavior โ which
this SDK can't verify for you, hence opt-in, off by default:
```python
mcp.add_middleware(LuluAdsMiddleware(cli_text_mode=True))
```
```typescript
withLuluAds(server, ads, { cliTextMode: true });
```
Turn this on only if your tool's `content[]` already contains a
complete, human-readable rendering of the result on its own โ not a
placeholder like "see structuredContent". When on, detected CLI clients
with no declared `outputSchema` get `structuredContent` stripped so
`content[]` (your tool's own text + our card) reliably reaches the
model. Tools that declare an `outputSchema` are never touched by this โ
stripping `structuredContent` there would break client-side schema
validation outright (confirmed: `fastmcp.exceptions.ToolError`
"outputSchema defined but no structured output returned"), which is a
broken tool call, a strictly worse outcome than a dropped card. This SDK
never drops `structuredContent.sponsored` on schema'd tools to chase card
visibility, `cliTextMode` or not.
Until the upstream client bug is fixed, treat the CLI card as "renders
reliably once you opt in and your tool qualifies, on top of a disclosure
that already works either way" โ same verify-in-your-own-host caveat as
the widget path above.
## Guarantees (enforced in code, not just promised)
| Guarantee | How |
|---|---|
| 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) |
| Always disclosed | `label: "Sponsored"` is set by the SDK, never sourced from the response body |
| No prompt injection, ever | we ship a data field; there is no display instruction anywhere in the contract |
| No PII leaves your server | `context` is filtered against an allowlist client-side, before any request is built |
| Quality-gated | every creative passes [Dali](https://dali.getlulu.dev) scoring (โฅ70) before it can fill a slot |
| Intent, not identity | targeting uses this call's stated context only โ no user profiles, no cross-session ID |
| Misconfigured? Still safe | missing credentials โ client is inert, returns `None`/`null`, zero network calls |
## Why not justโฆ
**โฆtell the model to mention a sponsor in its reply?**
Display instructions get MCP servers delisted by registries that scan for
injected directives. We ship a plain data object โ `label`, `text`, `url` โ
with no field, anywhere in the contract, that tells a model how to render or
phrase anything.
**โฆcount impressions and charge per view?**
An "impression" only exists if a model actually rendered it, and that's
unverifiable from the server side โ easy to game, hard to audit. We charge
CPA only, on a click that redeems a signed, server-verified token. Payment
maps to a real user action, not a claim.
**โฆscan the conversation to target better?**
Reading transcripts to target ads is a privacy trap: everything a user says
becomes ad-targeting data. We accept six allowlisted context keys โ `tool`,
`category`, `query`, `route`, `locale`, `country` โ stated intent for this
call only. No transcripts, no profiles, no PII fields exist in the schema.
## How it works
```
tool call
โ
โผ
your tool's own result
โ
โผ
POST /slot (1500ms cap โ 3000ms when classifying a raw prompt โ allowlisted context only)
โ
โผ
labeled data field { label: "Sponsored", text, url } โ attached, never injected
โ
โผ
host / model judgment โ renders it, or doesn't โ not our call
โ user clicks
โผ
GET /c/{token} โ signed redirect, click recorded
โ
โผ
advertiser's affiliate rails โ POST /postback on conversion
โ
โผ
70% publisher / 30% Lulu, on the ledger. Earnings accrue to your balance from the first audited conversion โ cash out from $100.
```
Full wire-level detail: [`docs/contract.md`](docs/contract.md).
---
Docs: https://getlulu.dev/docs ยท [Quickstart](docs/quickstart.md) ยท
[API contract](docs/contract.md) ยท [Integrations](docs/integrations.md) ยท
[Publisher signup](https://getlulu.dev/publishers) ยท Quality gate:
[Dali](https://dali.getlulu.dev) ยท [MIT](LICENSE)
## Changelog
- **0.8.1** โ Result-widget template gallery (supersedes 0.8.0, which
briefly shipped on npm with a louder strip design): `lulu_ads.widgets` /
`lulu-ads/widgets` with four predefined templates (`stat-card`,
`table-card`, `notice-card`, `carousel-card`), design tokens + `.lw-*`
primitives, and the disclosed SPONSORED strip built into the frame
(advertiser logo via the slot's new `logo_url`, letter-tile fallback).
`register_result_widget()` patches an already-registered FastMCP tool in
place (or returns the AppConfig for explicit `app=`).
- **0.7.4** โ Widget: the sponsored card's iframe canvas no longer paints
an opaque white box on dark hosts. `background: transparent` alone is
not enough for an embedded iframe: Chromium keeps the canvas
transparent only when the embedded document's used color scheme matches
the embedder's, and this document declared none (defaulting to
`light`), so dark-themed hosts (e.g. claude.ai in dark mode) forced a
white backdrop behind the card. The widget now declares
`color-scheme: light dark`, which resolves to the user's preferred
scheme โ matching hosts that follow it (claude.ai does by default) on
both light and dark themes. Verified empirically against light- and
dark-scheme embedding pages. (Also aligns `lulu_ads.__version__`, which
had drifted to 0.7.2 while the packages published as 0.7.3.)
- **0.7.0** โ Two real bugs, found live against a real third-party MCP
server behind Claude.ai's remote connector, both fixed:
- **0% ad delivery on hosts that reconnect per message** (confirmed:
Claude.ai opens a brand-new MCP session per chat message, not once per
conversation). Root cause: this SDK's persistent HTTP connection goes
cold on any real idle gap between messages, but only a one-time
"have I ever succeeded" check protected the very first call ever โ
every later cold call still got the tight steady-state timeout and
failed. Fixed by re-checking coldness on every call, keyed to time
since the last real success, not a permanent latch. Also: the fast
steady-state timeout itself was raised 800ms โ 1500ms
(Python and TS) โ production evidence showed even "warm" calls
sometimes measuring 796-802ms, right at the old line rather than
comfortably under it.
- **Ad fetched successfully, never seen by the model.** FastMCP/the
MCP TS SDK build a tool result's `content[]` once, from the tool's
original return value, before `LuluAdsMiddleware`/`withLuluAds` ever
run โ mutating `structuredContent` alone (the only thing this SDK's
own test suite checked) left `content[]` permanently stale. Confirmed
live: the wire response's `structuredContent` demonstrably had
`sponsored`, but Claude.ai read and reported back from `content[]`,
which didn't. Both SDKs now keep `content[]` in sync whenever it's
safe to (a single auto-generated JSON text block); regression tests
added for the exact gap that let this ship unnoticed the first time.
- **New:** `enable_lulu_ads()` (Python) / `enableLuluAds()` (TS) โ one
call that wires both the data field AND the rendered MCP Apps widget
onto every tool automatically, present and future. Existing
`register_sponsored_widget()`/`registerSponsoredWidget()` +
`app=`/`_meta.ui` per tool still works and is now documented as the
lower-level building block for per-tool control; the gap it left (an
easy-to-forget manual step per tool) is exactly what this closes โ
found live on our own dogfood server, which had wired the widget onto
exactly one tool by hand and silently never updated it for tools
added since.
- **0.6.2** โ The sponsored card now plays a one-time diagonal light sweep
across itself when it settles into the loaded state (a real ad won) โ
pure CSS (`.card-shine` in `js/widget-src/src/index.css`), fires exactly
once per mount (not a looping shimmer, since this sits inline in a real
chat thread), and respects `prefers-reduced-motion`. Skeleton and
no-fill states are unaffected.
- **0.6.1** โ Corrects a stale `0.6.0` published to npm before `dist/` was
rebuilt from the merged source (`js/` has no `prepublishOnly` build
step) โ 0.6.0 is deprecated on npm pointing here. Also fixes README.md
and both languages' `widget.py`/`widget.ts` docstrings, which
incorrectly claimed `text`/`url`/`logo` passed to
`register_sponsored_widget()` render as a fallback "house ad" until a
live `tool-result` arrives; they never do โ the widget shows the
skeleton indefinitely if a host never pushes it.
- **0.6.0** โ The MCP Apps sponsored widget now shows **live, per-call ad
content** instead of a fixed house ad baked in at registration time:
rebuilt in React + shadcn/ui (`Card`, `Skeleton`, `Button`), compiled to
a single self-contained bundle shared byte-for-byte by both SDKs
(`js/widget-src/`). The widget shows a skeleton immediately on load,
then listens for the MCP Apps host's own `ui/notifications/tool-result`
push โ which the spec already delivers once per call, to a fresh iframe
per call, with no server-side change needed โ and swaps to that call's
real `structuredContent.sponsored` data โ the widget shows the skeleton
indefinitely if a host never pushes it, not a fallback ad; only
`label`/`cta`/`accent*` from `register_sponsored_widget()`/
`registerSponsoredWidget()`'s options are actually used by the live
path. The "Powered by Lulu Ads" footer renders once, immediately, and
is never itself part of the skeletonโcard swap. Live-verified against a
real host (claude.ai) with a throwaway test server: skeleton renders
before the tool call resolves, swaps to the real per-call card once it
does, the footer never disappears or reflows during the swap, and two
tool calls in the same turn render two fully independent widget
instances, each showing only its own call's data โ confirming the "per
call, not per tool" behavior this feature is built on. (The CTA's
`ui/open-link` redirect โ vs. a raw navigation โ was re-confirmed by
static code inspection and this repo's existing unit tests during this
same pass; live click-through capture was attempted but blocked by
browser-automation tooling limits reaching inside the host's
double-sandboxed iframe, not by any observed product failure.)
- **0.4.0** โ Automatic pre-connect on construction for LangChain's
`LuluAdsAgentMiddleware`, CrewAI's `install()`, and TypeScript's
`withLuluAds` (matching the FastMCP `LuluAdsMiddleware`, which already
had this). Also: FastMCP's `LuluAdsMiddleware` and LangChain's
`LuluAdsAgentMiddleware` now additionally warm the **async** connection
pool their `await`ed `sponsored_slot()` traffic actually uses โ the
construction-time warm-up above only ever touched the sync client, a
separate pool the async path never touches. `LuluAds.async_warm_up()`
is fired once per instance from a real framework lifecycle hook on the
live serving event loop (FastMCP's `on_initialize`, LangChain's
`abefore_agent`), since a background thread can't safely pre-warm a
connection meant for a different event loop. Gated by the same
`auto_warm_up` flag as the sync warm-up (this async path is Python-only โ
TypeScript's `autoWarmUp` only ever had one pool to gate). This is the fix
that closes the cold-start gap for `dali-mcp` in production, which
consumes the async path. Short-TTL (default 45s) success-only cache in
both base clients, keyed on resolved category or a hash of the prompt
text. Corrected documentation: the real default timeout is 800ms (fast
path) / 3000ms (classify path) adaptive, not a flat 300ms.
- **0.3.7** โ `cliTextMode` (opt-in, off by default): fixes the Claude Code
content[]-drop bug for real, but only for tools whose `content[]` already
stands on its own without `structuredContent` โ live-tested both
qualifying and non-qualifying cases, see "CLI rendering". Never touches
tools with a declared `outputSchema` (would break client-side schema
validation, confirmed via `fastmcp.exceptions.ToolError`).
- **0.3.6** โ automatic connection warm-up on `LuluAdsMiddleware` construction
(`auto_warm_up`, on by default): a genuinely cold first tool call measured
804ms against the 800ms fast-path default โ right at the ceiling, not
under it. `LuluAds` itself still never auto-warms (a network call as a
constructor side effect is surprising in a general-purpose client), but
the middleware is the "one line, zero config" promise, so it warms itself.
- **0.3.5** โ fixed a hardcoded 300ms default `timeout_ms` on
`LuluAdsMiddleware` that silently dropped real, fillable ads on real
network latency โ every test in the suite used an instant mock transport,
which is exactly why this shipped unnoticed. Default is now `None`,
deferring to `LuluAds`'s own conditional 800ms/3000ms default.
- **0.3.4** โ CLI card gets rounded corners and a "via Lulu Ads" footer
(Unicode box-drawing only โ a live test against Claude Code confirmed it
strips raw ANSI color escapes from tool output before the model sees
them, so color was never on the table). Also live-tested and explicitly
rejected dropping `structuredContent` to force `content[]` through: it
does make the card arrive, but the model then flags it as suspected
prompt injection and warns the user off it โ worse than the status quo,
where the plain field still gets surfaced honestly even without the
card. See "CLI rendering" for the full writeup.
- **0.3.3** โ CLI-adaptive rendering: `LuluAdsMiddleware` / `withLuluAds` detect
known CLI clients via the MCP `clientInfo.name` sent at `initialize`
(currently: `claude-code`, verified live) and append a bordered plain-text
card to `content[]` for them, in addition to the plain field โ terminals
have no widget surface, so this is the CLI-safe equivalent of the MCP Apps
widget above. Still just data; see "CLI rendering" for the disclosed known
limitation on some clients' `content[]` forwarding.
- **0.3.0** โ `register_sponsored_widget()` / `registerSponsoredWidget()` gain
a `logo` option: fetched server-side at registration time and inlined into
the widget as a `data:` URI, so it renders under the widget sandbox's CSP
(`img-src 'self' data: