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; below 1 or not an integer it is 400 VALIDATION_FAILED.
cursor	string	no	The previous page's next_cursor; omit it for the first page. Send it with the same filters as the request that returned it: a malformed cursor, or one sent with other filters, is 400 INVALID_CURSOR.

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	Download name. Defaults to the leaf of path.
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.
session_id	string	no	Session the ingest runs for. The converter's generation and the chunk embeddings are metered against the session and its actor.
actor_id	string	no	Actor the ingest runs for when there is no session; metered like session_id. Beside session_id it must be that session's actor, else 400 VALIDATION_FAILED.

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; below 1 or not an integer it is 400 VALIDATION_FAILED.
cursor	string	no	The previous page's next_cursor; omit it for the first page. Send it with the same filters as the request that returned it: a malformed cursor, or one sent with other filters, is 400 INVALID_CURSOR.

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 creates.
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; below 1 or not an integer it is 400 VALIDATION_FAILED.
cursor	string	no	The previous page's next_cursor; omit it for the first page. Send it with the same filters as the request that returned it: a malformed cursor, or one sent with other filters, is 400 INVALID_CURSOR.

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.
session_id	string	no	Session the ingest runs for. The converter's generation and the chunk embeddings are metered against the session and its actor.
actor_id	string	no	Actor the ingest runs for when there is no session; metered like session_id. Beside session_id it must be that session's actor, else 400 VALIDATION_FAILED.

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