> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/manual/organisation/built-in-mcp-servers/knowledge-base-mcp-server.md).

# Knowledge Base MCP Server

The **Knowledge Base MCP Server** is a built-in server that gives your AI agents the ability to read, search, and manage your organisation's Knowledge Base directly during a conversation. Using this server, an agent can find relevant documents, read their full content, create new documents, organise folders, and update existing content - all without leaving the conversation.

> **Draft-first content, with agent-controlled publishing.** Every piece of content an agent writes lands in a **draft** first - this keeps unverified content out of search until it is explicitly published. Agents can publish drafts themselves using the `publish_document_version` tool (only draft versions can be published; rollback to a previous version is intentionally not available to agents). Renaming, moving, and updating summaries or metadata take effect immediately because those fields are never embedded into search.

## Connection Parameters

| Parameter          | Value                                                 |
| ------------------ | ----------------------------------------------------- |
| **Server address** | `internal://knowledge-base`                           |
| **Server type**    | Internal (built-in, no external credentials required) |

## Access Scopes

Before an agent can use any of the tools on this server, it must be granted access. There are three scope levels:

| Scope                | What the agent can see and do                                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **None** *(default)* | No knowledge base access. All tool calls will fail.                                                                                               |
| **All**              | Full access to every document and folder in your organisation's knowledge base.                                                                   |
| **Selected folders** | Access limited to one or more specific folders (and everything inside them). The agent cannot see or touch anything outside its assigned folders. |

> **Security note.** The scope is enforced at every tool call. A folder-scoped agent that tries to read, edit, or move something outside its assigned folders will receive a "not found" response - the same as if the item simply did not exist. This prevents the agent from even knowing whether content outside its scope is present.

## Key Concepts

### Documents and Folders

The Knowledge Base is organised as a tree of **folders** and **documents**.

* A **folder** is a container for documents and other folders. It has a name, an optional summary, and optional metadata. Folders are created and modified live - there is no draft step.
* A **document** holds Markdown-formatted content. It has a name, a body (the Markdown text), an optional summary, and optional metadata.

### Draft / Publish Workflow

When an agent **creates** or **edits** a document, the content is saved as a **draft**. Drafts are:

* ✅ Immediately visible to a human reviewer in the Knowledge Base editor.
* ❌ **Not** returned by search or the "get document" tool until published.
* ✅ Publishable by the agent itself via `publish_document_version`, or by a human in the Knowledge Base editor. Rolling back to a previously published version remains a human-only action and is not exposed to agents. Changes to a document's **name**, **summary**, or **metadata** are *not* drafts - they apply immediately.

### Metadata

Every document and folder can carry a **metadata** object: a free-form set of key-value pairs your organisation defines (for example: `owner`, `department`, `retention-class`, `external-id`). Metadata is descriptive information; it is never embedded or made searchable. It can be read and updated by agents, but updating it is a **full replacement** - see `set_metadata` for details.

## Tools Reference

## Available Tools

### Reading and Searching

<table data-header-hidden><thead><tr><th width="211.51171875"></th><th></th></tr></thead><tbody><tr><td><strong>Tool</strong></td><td><strong>Description</strong></td></tr><tr><td><code>search_documents</code></td><td>Search the knowledge base for content relevant to a question or topic. Combines <strong>semantic understanding</strong> (meaning-based) and <strong>keyword matching</strong> (full-text), so it finds relevant content even when the exact words are not used. Only <strong>published</strong> documents are returned - drafts are never surfaced in search.</td></tr><tr><td><code>get_document</code></td><td>Retrieve the full content of a specific document, including its complete Markdown body. Use this after <code>search_documents</code> to read the complete text of a result. Only published documents can be retrieved - an unpublished draft is reported as "not found". Each read records a <strong>citation</strong> on the document, helping your team understand which documents agents rely on most.</td></tr><tr><td><code>get_document_versions</code></td><td>Retrieve a document's whole version history, newest first, without the Markdown bodies. Unlike <code>get_document</code>, this is not limited to the published version - draft, publishing, published and archived versions are all listed, each with its version number, status and timestamps. Use it to find the <code>version_number</code> to pass to <code>get_document_version</code> or <code>publish_document_version</code>.</td></tr><tr><td><code>get_document_version</code></td><td>Retrieve one specific version of a document, including its Markdown body, addressed by its 1-based version number. Like <code>get_document_versions</code>, it is not limited to the published version - it can also return a draft, a version pending publication, or an archived one.</td></tr><tr><td><code>list_children</code></td><td>List the immediate contents (documents and sub-folders) of a folder, one level deep. Use this to browse the knowledge base structure step by step. For the complete nested tree at once, use <code>get_folder_tree</code> instead.</td></tr><tr><td><code>get_folder_tree</code></td><td>Return the full folder structure as a nested tree, showing the hierarchy of all folders and documents the agent has access to. Returns <strong>names and structure only</strong> - no document bodies or metadata. Use <code>get_document</code> or <code>list_children</code> to read those.</td></tr><tr><td><code>search_nodes_by_name</code></td><td>Find documents and folders by their <strong>title or name</strong>, rather than by their content. Matches items whose name contains the query text (case-insensitive). Use <code>search_documents</code> to search what documents say; use this to find a document or folder you already know the name of.</td></tr><tr><td><code>get_root_nodes</code></td><td>Return the ids of the knowledge base's top-level nodes as this agent is scoped to see them - its own assigned folders under <strong>Selected folders</strong> scope, or the organisation's actual top-level folders (for example "Organisation Documents" and "Assistant Documents") under <strong>All</strong> scope. Returns an empty list if the agent has no access. Pass a returned id as <code>root_id</code> to <code>get_folder_tree</code> or <code>parent_id</code> to <code>list_children</code> to browse from there.</td></tr><tr><td><code>get_current_node</code></td><td>Return the id of the knowledge-base node the user is currently viewing, or null if there is none. This is conversation context, not an access-scoped lookup - it never fails and never enforces the agent's knowledge base scope, so a returned id may still be outside what the agent can read.</td></tr></tbody></table>

### Creating and Editing Documents

<table><thead><tr><th width="214.61328125">Tool</th><th>Description</th></tr></thead><tbody><tr><td><code>create_document</code></td><td>Create a new document with Markdown content. ⚠️ The content is saved as a <strong>draft</strong> - it will not appear in search or be readable by other agents until published (via <code>publish_document_version</code>). The document's name, summary, and metadata take effect immediately.</td></tr><tr><td><code>update_document</code></td><td>Replace the entire Markdown body of an existing document. ⚠️ The edit is saved as a <strong>draft</strong> - the currently published content stays live and searchable until the new version is published (via <code>publish_document_version</code>).</td></tr><tr><td><code>publish_document_version</code></td><td>Publish a specific version of a document, identified by its <code>version_number</code> (from <code>get_document_versions</code>), making it live and searchable. Only draft versions can be published: calling it again on a version that is already publishing or published is a no-op that returns the version unchanged, while publishing an archived version fails. Rollback to a previous version is not available to agents.</td></tr><tr><td><code>rename_document</code></td><td>Change the title of an existing document without touching its body. Applies <strong>immediately</strong> - no draft or publish step.</td></tr><tr><td><code>delete_document</code></td><td>Permanently delete a document.</td></tr></tbody></table>

### Managing Folders

<table data-header-hidden><thead><tr><th width="211.15625"></th><th></th></tr></thead><tbody><tr><td><strong>Tool</strong></td><td><strong>Description</strong></td></tr><tr><td><code>create_folder</code></td><td>Create a new folder to organise documents and sub-folders. Takes effect <strong>immediately</strong> - there is no draft step for folders.</td></tr><tr><td><code>rename_folder</code></td><td>Change the name of an existing folder. Applies immediately.</td></tr><tr><td><code>delete_folder</code></td><td>Delete a folder and <strong>everything inside it</strong> - all sub-folders and documents are removed as well. ⚠️ This action cannot be undone.</td></tr></tbody></table>

### Organising and Annotating

<table data-header-hidden><thead><tr><th width="210.1875"></th><th></th></tr></thead><tbody><tr><td><strong>Tool</strong></td><td><strong>Description</strong></td></tr><tr><td><code>move_node</code></td><td>Move a document or folder to a different location in the hierarchy. Moving a folder also moves everything inside it. Branch-scoped agents can only move items within their assigned branch.</td></tr><tr><td><code>set_summary</code></td><td>Set or clear the short summary on a document or folder. Applies <strong>immediately</strong> - summaries are descriptive text for people browsing the knowledge base and are not embedded or made searchable.</td></tr><tr><td><code>set_metadata</code></td><td>Replace the metadata object on a document or folder. Applies <strong>immediately</strong>. ⚠️ This is a <strong>full replacement, not a merge</strong> - any key you omit will be permanently removed. To change a single key, first read the current metadata, apply your change, then send the complete updated object. Pass <code>null</code> to remove all metadata.</td></tr></tbody></table>