DEV Community: Birinchishop

How we let AI assistants manage an affiliate account without letting them spend the money

Birinchishop — Tue, 27 Oct 2026 12:37:35 +0000

By the Birinchi Shop team

Our earlier post was about the shopper side of Birinchi Shop: an AI assistant that finds a product and places a cash-on-delivery order. This one is about the other side, the people who bring those orders in.

Birinchi Shop is a CPA (cost-per-action) network in Uzbekistan. Partners (affiliates, media buyers, Telegram channel owners) pick a product, get a tracking link and promote it. A customer orders on the landing page, our call center phones them to confirm, a courier delivers, and the customer pays cash. The partner earns a fixed payout only when the order is delivered. Payouts depend on the product, typically from 30,000 to 100,000+ UZS. Income is not guaranteed; it depends entirely on the traffic.

That gives a partner a lot to watch: which offers sell, which links convert, why orders get stuck at "operator is calling", and whether a Meta ad campaign is burning money. So we gave them a public API and an MCP server. A partner can now connect Claude or ChatGPT to their account and ask "how did I do yesterday, and what should I change?".

The hard part was not the tools. It was deciding what an AI is allowed to do on its own.

One business layer, two front doors

Everything lives under /api/v1, rate-limited to 120 requests per minute per key:

a REST API with an OpenAPI 3.1 spec and a reference page;
an MCP server (/api/v1/mcp, stateless Streamable HTTP) for AI clients;
webhooks and postbacks for order status changes.

REST and MCP call the same service functions. An MCP tool is a thin wrapper that declares the scope it needs:

{
  name: 'list_orders', scope: 'orders:read',
  annotations: { readOnlyHint: true, title: 'List orders' },
  inputSchema: { /* status, date range, link, limit */ },
  run: (ctx, a) => svc.listOrders(ctx, a),
}

That rule kept us honest. Every permission check, rate limit and response filter exists once, and the AI path cannot quietly get more access than the REST path.

What the assistant can do

18 tools, grouped by scope:

Scope	Tools
`account:read`	`get_account` (balance, payout status)
`offers:read`	`search_offers`, `get_offer` (payout, sale rate, stock, the partner's existing links)
`links:read` / `links:write`	`list_links`, `create_link`
`orders:read` / `orders:write`	`list_orders`, `get_order`, `create_order`
`stats:read`, `events:read`	`get_stats`, `list_events`
`insights:read`	`get_insights` (yesterday + recommendations), `get_order_sale_chance`
`ads:read` / `ads:write`	`list_campaigns`, `get_ads_status`, `get_action`, `pause_campaign`, `resume_campaign`, `change_campaign_budget`

There are also four MCP prompts that show up in the client's / menu: Daily review, Find an offer to promote, Check my ad campaigns and Why are my orders not delivered?. Most partners are not developers; one tap is better than a well-written prompt they will never write.

The server instructions teach the model one piece of domain knowledge that matters more than any other:

sale_rate_percent is the share of finished orders that end up delivered. It matters more than payout: a 30,000 payout at 40% beats a 70,000 payout at 5%.

Without that line, models happily recommend the offer with the biggest number.

Rule 1: read-only by default

Partners connect through OAuth 2.1, no copy-pasting keys. The consent screen lists the scopes in plain language, and if the client asks for nothing specific, it gets only the read scopes:

const DEFAULT_SCOPES = ['account:read', 'offers:read', 'links:read', 'orders:read',
                        'stats:read', 'events:read', 'insights:read', 'ads:read'];

Write scopes must be requested and approved explicitly. Webhook management is never available over OAuth at all; that stays with API keys created in the panel.

Implementation notes, for those building the same thing:

PKCE with S256 only; authorization codes are single-use and live 5 minutes.
Access tokens live 1 hour, refresh tokens 30 days and rotate on every use.
Claude.ai registers itself via a client metadata document (its client_id is a URL), so we support that in addition to dynamic registration.
Every connected app is stored like an API key. Revoking it in the panel, or changing the password, kills its tokens.
When an app connects, the partner gets a Telegram message: "New app connected: … If this wasn't you, revoke it now."

Rule 2: writes that cost other people's time are earned

create_order sends a lead to a real call center. A brand-new account with an AI attached could flood it with junk. So the scope alone is not enough:

const ORDERS_WRITE_MIN_DELIVERED = 3;
// orders:write works only after the partner has 3 delivered orders,
// or an admin has enabled it manually

Creating a tracking link, on the other hand, is cheap and reversible, so links:write has no such gate.

Rule 3: stopping spend is instant, increasing it needs a human

This is the rule we like most. Meta ad campaigns spend the partner's own money, so the three ad actions are deliberately asymmetric:

pause_campaign runs immediately. Stopping spend is always safe, and when a campaign is clearly losing money, waiting is the expensive option.
resume_campaign and change_campaign_budget do not act. They create a confirmation card in the partner's Telegram bot and panel and return:

{
  "id": 412,
  "status": "pending_confirmation",
  "confirmation": {
    "required": true,
    "where": ["telegram_bot", "panel"],
    "note": "The partner must press \"Confirm\". Poll get_action for the result."
  }
}

The model is told to say "please press Confirm" rather than "done", and it can check the outcome later with get_action (pending, running, done, failed, cancelled, expired).

The confirmation happens outside the AI client, in a channel the partner already trusts. A prompt injection hidden in a product description or an ad comment can at most ask for a budget increase, and that ask lands on the partner's phone with the exact amount on it.

Rule 4: the API decides what leaves the server

Two kinds of data never go out:

Customer phone numbers are always masked. Partners see the last digits, enough to match an order, never the full number. The AI sees exactly the same.
Internal supply-side details, such as which supplier fulfils an order or their internal error messages, are not part of the partner's world.

We enforce both with allowlist serializers. Every response object is built field by field:

function order(o) {
  return {
    id: o.id,
    status: STATUS_PUBLIC[o.status] || o.status,
    conversion_status: CONVERSION[o.status] || 'lead',   // lead / approved / sale / rejected
    created_at: iso(o.createdAt),
    offer: o.offer ? { id: o.offer.id, name: o.offer.name } : { id: o.offerId, name: null },
    customer: {
      name: o.clientFullName,
      phone_masked: maskCustomerPhone(o.customerPhone),
      region: regionLabel(o.region, null),
    },
    payout: num(o.commissionAmount),
    payout_status: payoutStatus(o),
    // ...and nothing that wasn't written here on purpose
  };
}

Add a column to the database and it does not appear in the API until someone types it here. That is slower to develop and exactly what we want.

Webhooks without surprises

Partners who track conversions in their own tools get webhooks and postbacks on order status changes. Two details save a lot of support tickets:

Events come from the database, not the code. A trigger on the orders table writes every status change into an api_events table, so it does not matter which part of the system changed the status: the call-center sync, an admin, a cron job. Webhook delivery reads that table with a cursor.

Every delivery is signed:

X-Birinchishop-Event: order.status_changed
X-Birinchishop-Event-Id: evt_10293
X-Birinchishop-Signature: t=1761580800,v1=<hex HMAC-SHA256(secret, "<t>.<body>")>

Outgoing requests go through an SSRF-safe HTTP client: the target host is resolved first and refused if any address is private, loopback or cloud metadata, and redirects are never followed. "Enter your URL" is an invitation to point us at internal services.

Bugs worth sharing

The database lives in Europe/Berlin. Our Postgres server's time zone is Berlin; Prisma reads and writes UTC. Anything written by a trigger with plain now() came out one or two hours off and broke "events since" queries. Triggers now use now() AT TIME ZONE 'utc'. If you mix ORM writes and SQL triggers, check this first.

Tool descriptions are not a place for instructions. On our store server, the first descriptions said things like "Call ONLY after…" and "Never use…". They read as rules to the model, but for a connector directory they look like a tool trying to steer the model. We rewrote them as plain facts about what each tool does, and moved behavior guidance into the server instructions.

Not every client can do OAuth headers the way you expect. One MCP directory detected our OAuth metadata and silently dropped the custom Authorization header from its health check. Plain API keys in an X-API-Key header remain supported for exactly this kind of client.

What it is for

We designed the tools around questions partners already ask our support team, not around automation. Why are my orders still at "callback"? The model can call list_orders, see which customers the call center could not reach, and use get_order_sale_chance to show which of them have a history of refusing deliveries. Which offer should I run this week? It can compare sale rates and stock with search_offers instead of just picking the biggest payout.

An autopilot was never the goal. The goal was a colleague who reads the dashboard for the partner and has to ask before spending their money.

Try it: the docs and OpenAPI spec are at birinchishop.uz/reference, and an LLM-friendly guide is at /api/v1/guide.md. The MCP server URL for Claude or ChatGPT custom connectors is:

https://birinchishop.uz/api/v1/mcp

It needs a partner account. If you run traffic in Uzbekistan, you can sign up here. Earnings depend on your traffic and are not guaranteed.

Questions about the OAuth flow or the confirmation design are welcome in the comments.

How we built an MCP App for a cash-on-delivery store in Uzbekistan

Birinchishop — Tue, 27 Oct 2026 12:25:56 +0000

By the Birinchi Shop team

In Uzbekistan most online shopping still ends with cash. You pick a product, leave your name and phone number, a call-center operator phones you to confirm, and a courier brings the parcel 1–3 days later. You inspect it at the door and pay the courier in cash, or refuse it.

Birinchi Shop works exactly like that, with 300+ products and delivery to every region of the country. Recently we gave the store a public MCP server, so an AI assistant can search the catalog and place an order for a shopper. This week we turned it into an MCP App. Instead of a wall of JSON-ish text, the assistant now shows real product cards, a variant picker and an order form, right inside the chat.

This post covers how it is built and what broke when we first tried it in a real host.

The starting point: a small, stateless MCP server

Our shop server is deliberately boring. It runs on Express, with no SDK: one POST endpoint that speaks JSON-RPC 2.0 over Streamable HTTP. It keeps no sessions, needs no API key and uses no SSE stream. It exposes five tools:

Tool	What it does
`search_products`	keyword search over the catalog (Uzbek/Russian names), price filters
`get_product`	images, video, variants with their own price and stock, total to pay
`store_info`	delivery area, fee, cash-on-delivery, returns
`place_order`	places a real order that a call center will phone
`get_order_status`	needs the order id and the last 4 digits of the phone

place_order is the dangerous one, because every order costs a real operator's phone call. So the server enforces rules no matter what the model does:

customer_confirmed: true is required. Without it the call is rejected with a message telling the agent to ask the shopper first.
The phone must be a valid Uzbek mobile number.
The same limits as our website apply: one order per phone per product per 24 hours, at most three different products.
There is a per-IP hourly cap and a daily cap for the whole AI channel.
Every AI order is flagged for the admins.

Cash on delivery helps a lot here. Even if something goes wrong, nobody gets charged. A bad order costs us one phone call.

What an MCP App adds

The MCP Apps extension (io.modelcontextprotocol/ui) lets a tool point at an HTML resource. A host that supports it renders that HTML in a sandboxed iframe next to the tool result. The view and the host talk JSON-RPC over postMessage.

There are three pieces on the server side.

1. Tools point at a ui:// resource

const APP_URI = 'ui://birinchi-shop/store-v4.html';

const uiMeta = (invoking, invoked) => ({
  ui: { resourceUri: APP_URI },                          // MCP Apps standard
  'openai/outputTemplate': 'ui://birinchi-shop/store-v4.skybridge.html', // ChatGPT Apps SDK
  'openai/widgetAccessible': true,
  'openai/toolInvocation/invoking': invoking,
  'openai/toolInvocation/invoked': invoked,
});

// in the tool list:
{ name: 'search_products', _meta: uiMeta('Searching the store…', 'Products found'), ... }

Four of the five tools share one view: search, product, order and status. store_info stays text-only.

2. The resource itself

case 'resources/read': {
  const r = APP_RESOURCES.find(x => x.uri === msg.params?.uri);
  if (!r) return rpcError(msg.id, -32002, 'Resource not found');
  return rpcResult(msg.id, { contents: [{
    uri: r.uri,
    mimeType: r.mimeType,           // 'text/html;profile=mcp-app'
    text: readAppHtml(),
    _meta: {
      ui: { csp: { resourceDomains: ['https://birinchishop.uz'], connectDomains: [] },
            prefersBorder: false },
    },
  }] });
}

The CSP is tight. The view may load images and video from our own domain and nothing else, and it makes no network requests at all. Every call to the server goes through the host as tools/call.

3. The text result does not change

The tool still returns content (text) and structuredContent (JSON). Clients without UI support keep working exactly as before. The view just reads structuredContent.

One HTML file, no build step

The view is a single ~45 KB HTML file with inline CSS and JS: no framework, no bundler, no CDN. It works out what to render from the shape of the result:

function showResult(res) {
  const sc = res.structuredContent;
  if (res.isError || !sc)                       return showError(res);
  if (Array.isArray(sc.items))                  return showList(sc);      // search_products
  if (sc.total_to_pay && Array.isArray(sc.variants)) return openProduct(sc); // get_product
  if ('next_steps' in sc && 'order_id' in sc)   return showDone(sc);      // place_order
  if (sc.status_text)                           return showStatus(sc);    // get_order_status
}

Product names come from our database and some of them are messy, so all text goes into the DOM through textContent and a tiny h(tag, attrs, ...children) helper. There is no innerHTML anywhere.

The bridge itself is small: send ui/initialize, store hostContext (theme, CSS variables, locale, display mode), send ui/notifications/initialized, then listen for ui/notifications/tool-result. A ResizeObserver reports ui/notifications/size-changed, so the iframe grows when the shopper opens the order form.

Tapping a card calls get_product from the view. The model is not involved, so browsing is instant and costs no tokens.

Consent belongs in the UI

In the text-only version the model had to collect name, phone and region in chat, read the total back and get a "yes". That works, but it is easy to get wrong, and a confirmation the model typed for the shopper is still just text.

In the app, the shopper fills in the form themselves. The next screen repeats the product, variant, name, phone, region and the cash total, and has one button: "I confirm — place order". Only that tap sends place_order with customer_confirmed: true. The server-side rules still apply on top.

After a successful order the view calls ui/update-model-context, so the assistant knows the order already exists and does not place it again:

bridge.updateContext(
  `The shopper placed order #${o.order_id} in the store app ... Do not place this order again.`,
  { order_id: o.order_id, status: o.status }
);

get_order_status renders as a simple timeline: received → operator confirms → with the courier → delivered, paid in cash.

Four bugs that only showed up in the real host

Everything passed in our local harness, a headless Chrome page that iframes the view and plays the host. Then we opened it on a phone in Claude.

1. clientInfo vs appInfo

The first live run showed our fallback error screen. We had written the ui/initialize params from memory, MCP-style, with clientInfo. The view protocol uses appInfo:

await request('ui/initialize', {
  protocolVersion: '2026-01-26',
  appInfo: { name: 'birinchi-shop-app', version: '1.1.0' },   // not clientInfo
  appCapabilities: { availableDisplayModes: ['inline', 'fullscreen'] },
});

Our harness answered any ui/initialize; the real host validated the params. Lesson: copy the request shape from the SDK's types (spec.types.ts in the ext-apps repo), and make the error screen print the actual reason. We now show it in brackets, so a screenshot is enough to debug.

2. A white card in a dark chat

Next, the view rendered in a dark chat with a white background and washed-out green text. The host passes theme variables as light-dark(#fff, #262624). light-dark() resolves from the element's color-scheme, and we never set one, so it always picked the light value. Meanwhile our own accent colors followed data-theme="dark", hence the odd mix.

3. ...and then a black frame around it

The fix for #2 was color-scheme: dark on :root. That made things worse in a different way. When an iframe's root color-scheme differs from its embedding page, the browser paints the iframe with an opaque canvas background, and a dark rectangle appeared around our card. The final version sets color-scheme on the app container instead of the root, so the iframe stays transparent and the host variables resolve correctly:

#app { color-scheme: light; color: var(--fg); }
:root[data-theme="dark"] #app { color-scheme: dark; }

4. Hosts cache the resource

After every HTML change, the phone kept showing the old version. Hosts cache ui:// resources, so we now put a version in the URI (store-v4.html) and bump it with every change to the view. Reconnecting the connector refreshes the tool list.

A bonus trap, specific to our setup: the Puppeteer in our frontend was so old that its bundled Chromium could not parse optional chaining (?.). The harness has to use a current Chrome, or it reports syntax errors no real user will ever see.

Testing without creating orders

Every real place_order rings a real phone, so the server accepts one reserved reviewer number. That number runs all the validation (product exists, in stock, variant chosen, valid phone) but returns test: true and never creates an order. The view shows a "Test order" screen for it. Directory reviewers get the number in our submission notes, and it is how we test on production.

The harness itself is under 100 lines: a page with an iframe, a fake host that answers ui/initialize, forwards tools/call to the real server handler, and resizes the iframe on size-changed. A script then clicks through search → product → variant → form → confirm and takes screenshots in light and dark mode.

What we would tell someone starting today

Keep the text result first-class. The UI is an extra layer; plenty of clients will never render it.
Let the view call your tools directly for browsing. It is faster and keeps the model out of simple clicks.
Put irreversible actions behind a button the user taps, and still enforce the rules on the server.
Lock the CSP down and route all data through tools/call.
Version your ui:// URIs.
Test in a real host early, on a phone, in dark mode.

If you want to see it working, add our store server as a custom connector in an MCP client that supports apps:

https://birinchishop.uz/api/shop/mcp

No API key is needed. Ask for something like "find a watch in Birinchi Shop". The usage guide is at birinchishop.uz/en/ai-shopping.

Questions about the implementation are welcome in the comments.