> ## Documentation Index
> Fetch the complete documentation index at: https://docs-pos.solya.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent & MCP

> How the POS API is agent-ready: the required-permissions and agent-tier extensions, and the discover-then-call flow.

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:

```http theme={null}
GET /v1/auth/whoami
Authorization: Bearer <token>
```

```json theme={null}
{ "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:

<Steps>
  <Step title="Search">
    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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Invoke">
    Call the operation with a [bearer token](/en/developers/authentication). A success
    returns the raw payload; a failure returns the
    [error envelope](/en/developers/making-requests#the-error-envelope) with a
    `ResultCode` to branch on.
  </Step>
</Steps>

## Related

* [Authentication](/en/developers/authentication) — the bearer token and `whoami`.
* [Making requests](/en/developers/making-requests) — envelopes and pagination.
* [Error codes](/en/developers/error-codes) — the `ResultCode` map an agent branches
  on.