qaqnuz MCP Public API#
The qaqnuz public API is MCP-first: external agents and tools talk to your brand through a governed Model Context Protocol server that exposes a narrowed, opt-in subset of your brand's tools. The same authorization path that governs in-product tool calls governs every external call — there is no separate, weaker public path.
This site documents the implemented surface for developers and partners: authentication, the two MCP procedures (list_tools and call_tool), per-tool examples, the error model, and rate-limit semantics, with TypeScript and Python snippets throughout.
Status — transport availability. The v1 GA transport is stdio only. A public HTTP/SSE gateway at mcp.qaqnuz.uz/v1 is designed but not yet deployed — it rides platform GATE-5 infrastructure and is not live. Until it ships, there is no public HTTPS base URL to call; integrate over the MCP stdio transport (a local/sidecar process) as shown in Authentication. See Versioning & deprecation for what changes when the gateway lands.
What the API is#
A qaqnuz MCP server instance is brand-scoped and api-key-scoped. When a client connects with an api key, the server:
- Resolves the key to exactly one brand (tenant) and one role.
- Checks that the brand is entitled to the MCP surface (a plan gate).
- Exposes, via
list_tools, only the tools that are (a) enabled, (b) explicitly
flagged MCP-exposable, (c) not sensitive, and (d) within the api key's granted scopes.
- Runs every
call_toolthrough the full governed path:
tool lookup → policy evaluation (default-deny, exact scope match) → approval gate (if the tool requires approval) → execution → a standard result envelope.
You never get a tool you cannot call, and a key can only ever narrow what your brand's policy already allows — never widen it.
Core concepts#
| Concept | Summary |
|---|---|
| MCP server | A governed server exposing list_tools / call_tool. Brand-scoped, identified as qaqnuz-mcp v1.0.0. |
| Tool | A named, scoped capability (e.g. sheets.read). Each tool has an input JSON Schema, a stability tier, and a side-effect class. |
| Scope | A <resource>.<action> string (e.g. orders.write). An api key holds a set of scopes; wildcards are rejected. |
| Side-effect class | read, write, external, or sensitive. sensitive tools are never exposed over MCP. write/external may be approval-gated. |
| Stability tier | stable, beta, or deprecated — surfaced in each tool's description. Pin production calls to stable. |
| Result envelope | Every call_tool returns a fixed-shape result: success data (+ truncated), or a failure with an error_class and a sanitized_error. |
What is and isn't live#
| Capability | Status |
|---|---|
list_tools (governed, scoped) | Implemented (v1, stdio) |
call_tool (governed, scoped, approval-gated) | Implemented (v1, stdio) |
| Bearer / api-key auth (HMAC-SHA-256, constant-time) | Implemented |
| Per-api-key + per-brand rate limiting (fail-closed) | Implemented |
| Standard error envelope (5 error classes) | Implemented |
Public HTTPS gateway (mcp.qaqnuz.uz/v1) | Not yet public — blocked on GATE-5 platform infra |
MCP resources (list_resources / read_resource) | Deferred (post-GA) — see Resources |
Where to go next#
- Authentication — mint a key, present it as Bearer, connect over stdio.
- list_tools — discover the tools your key can call.
- call_tool — invoke a tool and read the result envelope.
- Tool examples — end-to-end read / write / approval-gated examples.
- Errors & error classes — the five error classes and how to handle them.
- Rate limits — limits, windows, and retry semantics.
This documentation describes only the public developer surface. Internal governance, infrastructure, and security material is out of scope here.