Data Scope and Authorization
Public MCP needs no authentication. This page explains what you read by default, what a credential adds, and what this service deliberately does not do.
Default: public read
Without an Authorization header the service reads as a guest and returns the content anyone sees when they scan the code — exactly what appears on the page after a phone scan.
This is the stable, supported path today, and the recommended way to start. Nothing to apply for, nothing to configure.
Extension: authorized read
With the header below, the service passes the token through to the backend and unlocks non-public content according to the identity behind it:
Authorization: Bearer <Caoliao JWT>Important: this is not the Open Platform API Key — the two are not interchangeable. Use the API Key with Open Platform MCP instead.
A public flow for obtaining a Caoliao JWT is not open yet; this page will be updated when it is. Until then, read organization data through Open Platform MCP.
Public MCP itself does not validate credentials or resolve organization membership; both happen in the backend.
The read-only contract
Every entity_get response declares the boundaries it honored:
{
"contract": {
"profile": "read-only-public",
"rules": {
"readOnly": true,
"publicOnly": true,
"singleOrgView": true,
"actionsExecutable": false
}
}
}| Rule | Meaning |
|---|---|
readOnly | All five tools are reads. There is no write capability |
publicOnly | This response contains public content only (the value changes for authorized reads) |
singleOrgView | One call sees one organization's data; no cross-organization aggregation |
actionsExecutable | Actions are listed, never executed |
Public MCP does not support submitting records, editing content or changing state. entity_actions_list tells you which form is available and gives you a humanUrl; the actual filling in is done by a person on a Caoliao page. When you need write capability, use Open Platform MCP.
Data freshness
Guest responses are cached for 120 seconds. A record submitted moments ago may therefore take up to two minutes to appear via a public read. Requests carrying a credential bypass this cache.
If your use case is latency-sensitive, mention this delay in your agent's prompt or your product copy — and do not let the agent present "not found" as "it did not happen".
Cross-organization access
One call reads only data within the organization that owns the QR code; there is no aggregating across organizations.
FAQ
What comes back if I query a non-public code without a credential?
The public portion of that code. If the code is not public at all, you get an error rather than an empty object. An empty object would break the field semantics: an absent field only ever means "not tracked", never "does not exist".
Do public and authorized reads return the same structure?
Yes. The difference is whether fields carry values, not whether fields exist. Code written against a public read needs no structural changes for an authorized read.