Documents

MCP tools for the Documents module. See the Documents module docs for permissions and data model.

list-documents

List documents

Arguments

Argument	Type	Required	Description
project_id	string	no	Project ID (optional)
path_prefix	string	no	Only documents filed under this directory. The prefix is a path boundary, not a substring: /reports returns /reports/q1.txt and never /reports-archive/q1.txt, and / selects the whole project. A leading slash is optional and a trailing one is ignored, so reports, /reports and /reports/ are the same filter. % and _ are literal characters, not wildcards.
include_withdrawn	boolean	no	Include withdrawn documents. A withdrawn document leaves every default read and is not in the knowledge index at all — its chunks are dropped when it is withdrawn — so this shows it in the listing but never in a search.
related_to	string	no	Only documents related to this one, on either side of the edge: what it points at, and what points at it. An id with no relations narrows the listing to nothing.
tags	array	no	Filter by tag pairs, written key:value (split on the first colon, so a value may contain colons). Repeat the parameter for several pairs; all must be present with exactly that value.
metadata	string	no	A MetadataFilter as JSON, url-encoded. It travels as JSON rather than as key:value pairs because the match is exact and a query string cannot otherwise say whether 3 is the number or the string.
limit	number	no	Results per page. Above the maximum it is clamped, and limit in the response reports the page served; below 1 or not an integer it is 400 VALIDATION_FAILED.
offset	number	no	Results to skip. Negative or not an integer it is 400 VALIDATION_FAILED.

create-document

Create a document

Arguments

Argument	Type	Required	Description
project_id	string	no	Project ID. Required for JWT auth; omit when using an project key.
content	string	yes	—
path	string	no	Logical path within the project (e.g. /reports/q1.txt). Defaults to /<filename>, or to /<document_id>.txt when neither is given — a document with no path is reachable only by its id, since a prefix filter never matches null.
filename	string	no	—
title	string	no	Document title
metadata	any	no	Arbitrary metadata object. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.
tags	any	no	Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.
chunk_strategy	string	no	How to split the content into embeddable chunks. whole (default) stores the content as a single chunk; size splits into fixed-size character windows with overlap. page is equivalent to whole for plain text.
chunk_size	number	no	Window size in characters when chunk_strategy=size. Defaults to 1000.
chunk_overlap	number	no	Overlap in characters between consecutive windows when chunk_strategy=size. Defaults to 200.

ingest-document

Ingest a file into a chunked document

Arguments

Argument	Type	Required	Description
wait	boolean	no	When omitted or false (default), processing runs in the background and 202 Accepted is returned immediately with status=pending. Pass true to block until processing completes and receive 201 Created with status=ready.
file_id	string	yes	ID of the uploaded file. Must be one of application/pdf, text/plain, text/markdown.
project_id	string	no	Project ID. Required for JWT auth; omit when using a project key.
path_prefix	string	no	Path prefix under which to store the document (e.g. /docs/). The filename is appended automatically.
tags	any	no	Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.
chunk_strategy	string	no	How to split the source into chunks. page (default) creates one chunk per non-empty page (PDF); for non-paged sources it yields a single chunk. whole joins everything into one chunk. size splits into fixed-size character windows with overlap.
chunk_size	number	no	Window size in characters when chunk_strategy=size. Defaults to 1000.
chunk_overlap	number	no	Overlap in characters between consecutive windows when chunk_strategy=size. Defaults to 200.

get-document

Get a document by ID

Arguments

Argument	Type	Required	Description
document_id	string	yes	Document ID

delete-document

Delete a document

Arguments

Argument	Type	Required	Description
document_id	string	yes	Document ID

update-document

Update a document

Arguments

Argument	Type	Required	Description
document_id	string	yes	Document ID
content	string	no	New text content
title	string	no	New title
path	string | null	no	Logical path within the project (e.g. /reports/q1.txt). Pass null to clear.
metadata	any	no	Arbitrary metadata object, replacing the stored bag; null clears it. Unlike other body fields, keys are stored and returned verbatim in the casing supplied — they are not converted between snake_case and camelCase.
tags	any	no	Key-value labels on a resource. A flat object of string values — an array, a nested object or a number is rejected with 400 VALIDATION_FAILED, never coerced. Keys are opaque and stored verbatim, so cost_center and costCenter are two different tags. Matched by JSONB containment wherever tags are read: the ?tags= filter, knowledge search, and the IAM soat:ResourceTag/<key> condition. Keys beginning system. are reserved: the platform writes them to record which conversation, actor, agent and role a row came from, and a write naming one is refused with 400 RESERVED_TAG_KEY. They are read and filtered like any other tag. The bag is bounded, because every pair reaches the IAM context of every access check on the resource: at most 50 keys, each key at most 128 characters and each value at most 256. A write past a bound — including a merge that would grow the stored bag past the key count — is 400 VALIDATION_FAILED with meta.limit naming the bound it crossed. system.* keys are the platform's and do not count against the 50.
expected_version	any	no	Refuses the write unless the document is at this version.

list-document-relations

List a document's relations

Arguments

Argument	Type	Required	Description
document_id	string	yes	—
limit	number	no	Results per page. Above the maximum it is clamped, and limit in the response reports the page served; below 1 or not an integer it is 400 VALIDATION_FAILED.
offset	number	no	Results to skip. Negative or not an integer it is 400 VALIDATION_FAILED.

create-document-relation

Assert a relation

Arguments

Argument	Type	Required	Description
document_id	string	yes	—
type	string	yes	What this document claims about the other
to_document_id	string	yes	The document the edge points at. Must be in the same project, and visible to the caller.

delete-document-relation

Retract a relation

Arguments

Argument	Type	Required	Description
document_id	string	yes	—
relation_id	string	yes	—

get-document-status

Get document ingestion status

Arguments

Argument	Type	Required	Description
document_id	string	yes	Document ID

withdraw-document

Withdraw a document

Arguments

Argument	Type	Required	Description
document_id	string	yes	—
version_label	string | null	no	Optional tag for the tombstone version this write archives.
expected_version	any	no	Refuses the withdrawal unless the document is at this version.

list-document-versions

List a document's content versions

Arguments

Argument	Type	Required	Description
document_id	string	yes	—
limit	number	no	Results per page. Above the maximum it is clamped, and limit in the response reports the page served; below 1 or not an integer it is 400 VALIDATION_FAILED.
offset	number	no	Results to skip. Negative or not an integer it is 400 VALIDATION_FAILED.

get-document-version

Fetch an archived document version

Arguments

Argument	Type	Required	Description
document_id	string	yes	—
version	number	yes	—

restore-document-version

Restore an archived document version

Arguments

Argument	Type	Required	Description
document_id	string	yes	—
version	number	yes	—
label	string | null	no	Optional tag for the version this restore archives. Defaults to restored from v<version>.

reingest-document

Re-ingest an existing document

Arguments

Argument	Type	Required	Description
document_id	string	yes	Document ID
wait	boolean	no	When omitted or false (default), processing runs in the background and 202 Accepted is returned immediately with status=pending. Pass true to block until processing completes and receive 201 Created with status=ready.
chunk_strategy	string	no	How to split the source into chunks. Defaults to page.
chunk_size	number	no	Window size in characters when chunk_strategy=size. Defaults to 1000.
chunk_overlap	number	no	Overlap in characters between consecutive windows when chunk_strategy=size. Defaults to 200.

complete-ingestion-callback

Deliver an async converter result

Arguments

Argument	Type	Required	Description
document_id	string	yes	Document ID
token	string	yes	Single-use signed token from the original callback.token
text	string	no	—
pages	array	no	—

get-document-tags

Get document tags

Arguments

Argument	Type	Required	Description
document_id	string	yes	Document ID

replace-document-tags

Replace document tags

Arguments

Argument	Type	Required	Description
document_id	string	yes	Document ID

merge-document-tags

Merge document tags

Arguments

Argument	Type	Required	Description
document_id	string	yes	Document ID