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