> 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://k-ai.gitbook.io/knowledge-ai/k-ai-mcp/schema-stability.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.