Requirements

Step 1 — pick a path

Most partners do both, and the order matters: Path B answers questions about a customer’s own records only once Path A exists. If you already run an MCP server, Path A is close to done.

Path A — Option 1 · fastest

A1

A public HTTPS endpoint speaking MCP over Streamable HTTP.Must

Accepted whenIt resolves to a public address. We reject loopback, private, link-local and CGNAT ranges, and re-check every redirect hop.

A2

Stable tool names, and a JSON Schema for every argument.Must

Accepted whentools/list returns a manifest with no free-form object arguments. Untyped arguments become a text box a person has to guess at.

A3

Annotations on each tool: readOnlyHint and destructiveHint.Must

Accepted whenReads and writes gate separately in our setup dialog. Writes stay off until an admin turns them on, and destructive calls ask the user first.

A4

Auth: a static bearer token, or OAuth 2.1 with metadata discovery.Must

Accepted whenOne credential reaches exactly one of your tenants. Anything broader is a blocker, not a finding.

A5

A sandbox tenant with realistic data and throwaway credentials.Must

Accepted whenWe can exercise the full tool surface, writes included, without touching a real customer.

Path A — Option 2

R1

Base URL plus an OpenAPI 3.x document, versioned in the path or a header.Must

Accepted whenThe spec matches what the server actually returns. We build tools from it directly.

R2

A documented auth header. Per-user tokens strongly preferred over one service account.Must

Accepted whenA call made through the assistant is attributed to the real person and limited by their permissions in your system — not by ours.

R3

List endpoints with paging, sorting, per-field filters and a column selector.Must

Accepted whenA question about 5,000 records is a handful of requests. An assistant that has to page through everything gives up mid-answer.

R4

Server-side counts and aggregates on those list endpoints.Should

Accepted when“Which machine had the most parts replaced?” is one request. Without it, it is one request per machine and the answer never arrives.

R5

Honest HTTP status codes. A failure is 4xx or 5xx, never a 200 carrying success: false.Must

Accepted whenOur retry, rate-limit and reconnect logic reads the status. A 200-wrapped failure is silently treated as an answer.

R6

Stable record ids and a modified_at on everything indexable.Must

Accepted whenWe can sync incrementally and detect deletions instead of re-reading your database nightly.

R7

Published rate limits, with 429 and Retry-After.Must

Accepted whenWe back off correctly rather than discovering your ceiling in production.

R8

An entitlement endpoint: which of your modules this customer actually has.Should

Accepted whenThe assistant only offers what they bought, instead of promising a feature and returning a 403.

R9

Binary endpoints return raw bytes and a correct content type; writes accept an idempotency key.Should

Accepted whenPDFs and attachments reach the user as a download, and a retried request does not create a second ticket.

Path A — Option 3

The right shape when your data model is wide and the questions are open-ended. One query surface answers things nobody anticipated, and we generate tools from your column dictionary instead of one tool per endpoint. The cost moves rather than disappears: the failure is no longer a missing endpoint but a malformed query — which is why Q4 and Q5 carry more weight here than anywhere else on this page.

Q1

A resource catalogue: every table or view you expose, its columns and types, and which of them are filterable and orderable.Must

Accepted whenWe can hand the model a column dictionary. Without one it guesses names, and every third question comes back a 400.

Q2

Curated views, not the raw schema.Must

Accepted whenWhat is reachable is a deliberate allowlist holding the columns you are willing to have read aloud — not select * over production tables.

Q3

Row-level security on every exposed resource, keyed to the caller’s credential.Must

Accepted whenA token scoped to one customer returns nothing for another’s rows however the query is written. On a generic surface, URL construction is not a permission model.

Q4

The exact grammar you accept: which operators, which relationships may be embedded and under what names, and whether aggregates are switched on.Must

Accepted whenIt is written down. PostgREST ships with aggregates disabled — a count() that quietly fails costs a day of both our time.

Q5

Errors that name the offending column or operator.Must

Accepted whenA 400 says which field it rejected. A bare “invalid query” is undebuggable on a generic endpoint: the model cannot correct itself and retries the same thing until it gives up.

Q6

Server-side ceilings: a default row limit, a hard maximum, and a statement timeout.Must

Accepted whenA badly shaped query is refused in milliseconds instead of scanning a large table. Assume every query is machine-written, because it is.

Q7

Stable resource names, and a schema-cache reload in your deploy.Should

Accepted whenA new column is queryable the moment it ships, and renaming a view is treated as a breaking change under rule 3.

Path B

E1

The exact hosts that may load it — app.acme.com, *.acme.com.Must

Accepted whenHTTPS only, apex and subdomains listed separately. This allowlist is the perimeter: the key in your page source identifies the assistant, it authorises nothing.

E2

One script tag in your app shell, and room in your CSP for our origin.Must

Accepted whenscript-src, frame-src and connect-src admit us. The panel is an iframe; a strict CSP blocks it silently.

E3

Verified identity: your server computes HMAC-SHA256 over the user id with the embed secret, and passes it alongside the id.Must

Accepted whenThe hash never touches browser code. Without it, the user id is a claim anyone can edit in devtools, and no user-specific tool may run.

E4

A backend endpoint that mints a short-lived credential for the signed-in user and posts it to us, server to server.Should

Accepted whenThe assistant acts as that person against your API, so your own permissions decide what it can see. Skip it and the panel answers from documents only.

E5

Content for the corpus: product documentation, help centre, release notes, policies.Must

Accepted whenA URL we may crawl, or an export. This is what the assistant answers from when no tool applies.

E6

Presentation: accent colour, panel title, greeting, four starter questions, and the topics it must refuse and hand off instead.Must

Accepted whenSupplied per language you ship in. Billing disputes, legal and security incidents are typical hand-offs.

E7

A retention period for conversations, and a signed DPA.Must

Accepted whenYour users are the data subjects. The panel always shows an “you are talking to an AI” line — that one is not configurable off.

Both paths

Seven things that are not negotiable

1. 1TLS 1.2 or better, on a publicly resolvable hostname. No IP literals, no internal-only endpoints, no self-signed certificates.
2. 2One credential reaches one customer. If a token issued for customer A can read customer B, the integration stops until it cannot.
3. 3Breaking changes get 30 days’ notice and a version that lets both shapes run during the window.
4. 4A named technical contact and a security contact, with a stated response time for a broken integration.
5. 5A sandbox that mirrors production shapes. Different data, same fields, same errors, same limits.
6. 6No secret in the browser, ever. Signing, minting and API keys stay on your server.
7. 7Write access is opt-in per capability. We ship read-only by default and let the customer’s admin enable the rest.