Agent & MCP - Solya POS Docs

Every documented operation is built to be driven by an autonomous agent. Two vendor extensions on each operation, plus a permission-introspection route, let an agent discover what it may call and how safe each call is — without reading the code.

`x-required-permissions`

Each operation advertises the pos.* scopes it enforces in an x-required-permissions array. This is derived from the route’s scope, not hand-written: a read stamps the scope’s read permission, a mutation stamps its write permission — the same scope constant the route guard enforces. So the documented requirement can never drift from what the server actually checks. An agent reads this to know, per operation, which scopes it needs.

`x-agent-tier`

Each operation carries an x-agent-tier marking how the MCP gateway should surface it. The backend authors tiers in a safety-first internal vocabulary, then maps them to the gateway’s vocabulary when the served spec is emitted:

Authored tier	Served tier	Gateway behaviour
`preferred`	`preferred`	Surfaced first in discovery (the default).
`supported`	`preferred`	An ordinary, usable mutation — first-class.
`avoid`	`advanced`	Callable, but excluded from discovery unless the agent opts in — a dangerous or irreversible operation is never nudged.

The mapping happens at the last step before the document leaves the process because the gateway collapses any tier it does not recognize to preferred — so the served spec speaks exactly the gateway’s four valid words (preferred, advanced, deprecated, hidden), and the safety tiering is preserved. A danger-lexicon guardrail keeps a genuinely dangerous verb from being authored preferred.

whoami — what may this agent do?

Before choosing operations, an agent introspects its own effective scopes:

GET /v1/auth/whoami
Authorization: Bearer <token>

{ "data": { "effectivePermissions": ["pos.sale.create", "pos.report.view"] } }

The returned scopes are the same vocabulary the operations advertise as x-required-permissions, so an agent can filter the surface down to operations it is authorized for. The MCP gateway hardcodes ${baseUrl}/api/auth/whoami, which the backend exposes as a byte-for-byte alias of /v1/auth/whoami — same handler, same auth, same response — so the gateway gets a real answer instead of failing open.

The discovery flow

An agent drives the API in three steps:

Fetch the served spec (GET /openapi.json) and select candidate operations by tag, operationId and the agent-facing description. Only documented, intentionally-exposed operations appear; advanced-tier operations are excluded unless the agent opts in.

Describe

For a candidate, read its description, parameters, request/response schemas and examples, its x-required-permissions, and its x-agent-tier. Cross-check the required permissions against whoami.

Invoke

Call the operation with a bearer token. A success returns the raw payload; a failure returns the error envelope with a ResultCode to branch on.

Authentication — the bearer token and whoami.
Making requests — envelopes and pagination.
Error codes — the ResultCode map an agent branches on.

​x-required-permissions

​x-agent-tier

​whoami — what may this agent do?

​The discovery flow

​Related

`x-required-permissions`

`x-agent-tier`

whoami — what may this agent do?

The discovery flow

Related