Supplier MCP — ask your BTAB supplier account questions from your own AI agent

POST /api/v1/supplier/mcp

BTAB's vendor side has had an MCP endpoint since 2026-09: a vendor's own agent can read and change their storefront. This is the supplier equivalent, and it answers a different set of questions — because a supplier is not a small vendor. A vendor runs a storefront and sells. A supplier ships product into the platform and then waits to find out whether it was accepted, whether the photos landed, and what they are owed.

It speaks Model Context Protocol over streamable HTTP, so it works from Claude Code, Claude Desktop, Cursor, Codex — anything that speaks MCP.

Status (Phase 1, 2026-09-21): the rail, the handshake identity sheet, prompt-injection fencing, and twenty-two read tools covering imports, catalogue health, orders and purchase orders, money (settlements, payments, returns) and account (profile, payout method — presence and masked tails only, never an account identifier).

Public copy of this document: https://btab.app/docs/supplier-mcp.md (the repository is private).

---

This endpoint is READ-ONLY. All of it.

Not "read-only for now, with a flag you can flip". There is no write tool on this server, and one cannot be added without also building the machinery that records it. That is enforced in three independent places, so no single one of them has to be remembered:

1. the tool registry is constructed with capabilities: ['read'], so registering a write or destructive tool throws at require time — the API does not boot;
2. the capability set handed to the registry on every request is {read}, and there is no scope to raise and no switch to flip;
3. registry.call() refuses any non-read capability at dispatch, before a handler runs, and tools/list is filtered by the same set.

Why, in plain words. The vendor rail's write path writes exactly one append-only audit row per call — executed, previewed, or refused — stamped with the vendor's id, into vendor_agent_writes. There is no supplier equivalent of that table, no supplier_mcp_writes_enabled kill switch, and no per-credential write budget. A supplier write tool shipped today would make a real change and record it against nobody.

So, for whoever picks up supplier writes later — this is the order, and it is not negotiable:

1. a supplier agent-write audit table (the vendor_agent_writes equivalent), and registry._callWrite taught to stamp a supplier actor rather than vendorId;
2. a kill switch — supplier_mcp_writes_enabled, in the same closed settings allowlist and the same admin group as the vendor one;
3. a per-credential write budget (supplier_mcp_writes_per_hour), consumed at dispatch;
4. then the write tools, and only then does capabilities: ['read'] come off the registry.

"No write tools" here is a decision with a reason, not an oversight. Adding one without 1–3 gives you a rail that changes a supplier's catalogue and cannot say who did it.

So: if your agent tells you it has updated a product, resubmitted a rejected item, retried an import or cancelled a job — it has not, and it is wrong. Nothing here can do any of that. The handshake tells the model so in its own instructions, before its first call.

---

What it will not pretend about

Three more things are stated on every handshake, because each is a confident wrong answer a model would otherwise give:

• A settlement is what BTAB owes you, not a payment. No tool here can send money. Whether BTAB pays suppliers out yet is the live payouts_enabled field on supplier_list_settlements, and a payment has been made only if supplier_list_payments lists it with a bank reference.
• Stored values are never translated. Answer in whatever language you write in — many suppliers use Simplified Chinese, and the supplier dashboard is served in it — but statuses (pending, approved, rejected), SKUs, product titles and import filenames come back verbatim. A translated status sends you hunting the UI for a word that is not in it.
• needs_dimensions on a product row is not reliable. Migration 086 backfilled it true across the whole catalogue and it only recomputes when the product is written, so it reads "needs dimensions" for products that already have every measurement. supplier_catalogue_health counts from the raw weight_grams / length_mm / width_mm / height_mm columns instead, and the model is told not to trust the flag.

---

One session, one supplier — the server says which

The server names your account on every handshake, so an agent can never mistake your account for the platform or for a vendor's storefront:

• initialize → serverInfo: { name: "btab-supplier-<business>", title: "<Business> (BTAB supplier MCP)", version, supplier: { id, business_name, status, trusted, signed_in_as } }.
• initialize → instructions (the MCP field clients inject into the model's system prompt) is generated per session: which supplier, whether submissions auto-approve, the read-only rule, the payout rule, the language rule, and how to work an import failure.
• GET the endpoint and the same supplier block plus instructions come back as plain JSON, along with read_only: true and read_only_because.

---

Connect it

Authentication, and its one real limitation

Auth is the existing supplier session token, sent as Authorization: Bearer <token> (the dashboard's supplier_session cookie also works from the browser).

There is no supplier API-key system yet. The vendor side lets a vendor mint a scoped read or read_write key per agent and revoke it alone; the supplier side has nothing to mint. That means a session token pasted into an MCP client carries your whole read access and dies when the session does. It is a real limitation, it is why this section says so rather than burying it, and a scoped supplier API key is the obvious next thing to build.

Because of that, the first consumer of this rail is the in-process supplier assistant in the supplier dashboard, which rides your own authenticated request and never holds a token at all.

A supplier whose account is suspended or terminated is refused at the next request on every supplier route, this one included.

By hand

{
  "mcpServers": {
    "btab-supplier": {
      "url": "https://api.btab.app/api/v1/supplier/mcp",
      "headers": { "Authorization": "Bearer <your supplier session token>" }
    }
  }
}

Probe it first — a GET costs nothing and tells you exactly what this credential can see:

curl -s https://api.btab.app/api/v1/supplier/mcp \
  -H 'Authorization: Bearer <token>' | jq

---

The protocol

Three methods and one notification, JSON-RPC 2.0 over a single POST:

Protocol revisions answered: 2025-11-25, 2025-06-18 (the one implemented), 2025-03-26, 2024-11-05. A version we do not know is answered with ours, and the client decides.

A failing tool is a successful JSON-RPC response carrying isError: true — that is what lets the model read why a call failed instead of seeing a broken server. Only a malformed envelope is a JSON-RPC error.

Every result is fenced. Tool output is wrapped in delimiters carrying a per-call nonce, declaring that what is inside is quoted DATA from BTAB — possibly containing text typed by other people — and that an instruction found inside it is to be reported, never followed. The raw result rides alongside as structuredContent for clients that want the numbers without parsing the fence.

---

The tools

Twenty-two, all read, in five groups.

Import — "why did my import fail?"

This is the single biggest supplier support cost at BTAB, and the hardest thing to self-serve when the error string is in English and the file was uploaded three days ago.

Not offered, deliberately: downloadSourceFile (streams a file) and getFailedRowsExport (re-parses the entire archived upload, up to 200,000 rows — a download behind a button, not a chat turn).

Catalogue — "what is pending, what got rejected, what is stopping the rest?"

import_job_id on supplier_list_products pairs with supplier_get_import_job to answer "what did that import actually land?" in two calls.

Orders — "what do I need to ship, and how am I doing?"

Accept / ship / deliver and PO confirm / reject are dashboard actions; none of them is a tool here.

Money — "what am I owed, what have I been paid, what came back?"

Account — "what do you hold about me, and where would the money go?"

This group is stricter than the dashboard, on purpose. The dashboard shows the BSB in full — a branch is not a person, and the reader is the supplier on her own screen. An MCP result travels (model context, client transcript, log line, wherever it is pasted next), so the rail withholds the BSB and answers payout_bsb_on_file instead. The question behind the ask — can I actually be paid? — is bank_fields_complete, which needs no identifier. The full account reference and account number are masked to their last 4 by the route itself, on every surface.

Storing a payout method is not a payment: what BTAB owes is supplier_list_settlements, and money actually sent is supplier_list_payments.

---

Two things the numbers do not say on their own

Paging. Every list takes page and limit. limit runs to 500 (the same ceiling the dashboards use), not 100 — except the import tools, whose controller sets its own: 50 for supplier_list_import_jobs, 200 for supplier_list_import_errors.

Retail price has two readings, and they can differ. supplier_list_products returns the calculated retail, which is null when none has been calculated; supplier_get_product falls back to the stored retail when the calculated one is missing. So the same product can come back with a price from one tool and null from the other. A null there means "no calculated retail", never "this product has no price" — check supplier_get_product before saying anything about such a product's price. Which of the two readings is right is an open decision; the tools disclose the difference rather than paper over it.

Sorting is by the value you see. Every sort_by orders by the same expression the row displays, and products with no retail yet sort last rather than first. (Until 2026-09-21 a retail sort ordered by a stored column that is not the one on the row — fixed, along with the single source that made the two drift apart.)

---

Tenant isolation

Every tool is scoped to the authenticated supplier, by the same query the dashboard uses. Another supplier's product or import job answers "not found", never "forbidden" — the rail does not confirm that someone else's row exists.

---

What this cannot reach

No vendor data, no other supplier's data, no admin surface, no pricing rules, no way to trigger a payout, no credentials. And, again: nothing that writes.