> For the complete documentation index, see [llms.txt](https://k-ai.gitbook.io/knowledge-ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://k-ai.gitbook.io/knowledge-ai/k-ai-mcp/schema-stability.md).

# Schema stability policy

K-AI's two MCP servers — Retrieval and Audit — are both stable. This page describes what we commit to keep stable and what may evolve, how versions are surfaced, and what deprecation looks like.

## What's stable

* **REST contracts of the underlying APIs.** Paths and request/response shapes of the Retrieval API (5 operations) and the Audit API (48 operations) are stable. They follow standard semver via the OpenAPI `info.version` field on each spec.
* **OAuth 2.1 flow.** Dynamic Client Registration (RFC 7591), Authorization Code with PKCE (S256), signed access tokens, and refresh-token rotation are stable. The discovery document, endpoint paths under `/auth/oauth/`, and the `mcp` scope name are stable.
* **Tool names and schemas for both MCP servers.** All 5 Retrieval tools (`retrieval_instances_list_available_instances`, `retrieval_documents_list`, `retrieval_documents_get_document`, `retrieval_documents_list_by_ids`, `retrieval_semantic_nodes_search`) and all 21 Audit tools (the curated conflict-first subset of the Audit REST API) have stable names, inputs, outputs, and error semantics.

## What may evolve

* **The set of operations exposed as MCP tools.** New tools may be added as the curated subset grows; this is additive and never a breaking change.
* **Tool descriptions and prompts.** Human-readable descriptions, parameter docs, and prompts attached to tools may be revised to improve agent ergonomics.
* **Backwards-compatible additions to response payloads.** New optional fields may be added to existing tool outputs.

## Versioning

* **REST APIs.** Each OpenAPI spec carries a `version` in its `info` block. Semver applies: patch (bugfix), minor (additive, backwards-compatible), major (breaking).
* **MCP tools.** Tool names follow the underlying `operationId`. A breaking change in tool inputs or outputs is reflected as a major bump on the corresponding REST spec.
* **Where to see changes.**
  * Audit API and Audit MCP: [`audit/changelog.md`](/knowledge-ai/k-ai-audit/changelog.md).
  * All surfaces (Retrieval, Instance, Audit): [`reference/changelog.md`](/knowledge-ai/reference/changelog.md).

## Deprecation policy

For any breaking change to a stable surface (REST contracts, OAuth flow, MCP tool names or schemas on either server):

* A deprecation notice is published in the relevant changelog at least **90 days** before removal.
* During the 90-day window, the deprecated tool or endpoint remains available **in parallel** with its replacement.
* Removal happens in a major version bump.