MCP server & tool reference

Setting	Value
Endpoint	/mcp on your SimpleDMS installation, for example https://simpledms.example.com/mcp
Transport	Streamable HTTP, stateless, with JSON responses
Authentication	Authorization: Bearer <token> on each request
Scope	One account-owned credential bound to exactly one organization and Space
Modes	Read-only by default, or read/write

Create credentials in the SimpleDMS web application under «MCP». The token is shown once. Use a client that supports a remote Streamable HTTP server with a configurable bearer header. SimpleDMS does not provide OAuth sign-in for this connection. Account passwords, browser session cookies, and WebDAV credentials do not replace an MCP token.

Current account and Space access, credential mode, and revocation are checked on requests and tool execution. A token cannot access another Space even if its owner can. Read-only credentials can discover the complete tool catalog, but write calls are rejected. Changing scope or mode requires a new credential.

HTTPS is required outside development mode. If a client sends an Origin header, its scheme and host must match the request origin. Behind a TLS-terminating reverse proxy, configure the public origin and trusted proxies. Application lock or maintenance and unavailable organizations can prevent access.

In the tables, ? marks an optional input. All entity IDs are public identifiers returned by the server, not numeric database IDs. No tool takes a Space selector. Start with get_space to discover the bound Space and root_directory_id.

Paginated lists use offset? and limit?. Offset defaults to 0, limit to 50, and the maximum limit is 100. Results include has_more and next_offset. Offset pagination is not a snapshot across concurrent changes. The template catalog is returned without pagination.

Tools return structured JSON data, with a JSON text fallback for clients consuming text content. Document results include browser URLs where available. Separate write calls are separate transactions, not one atomic batch. After a lost response, inspect the state before retrying an upload, creation, or filing operation.

Tool	Access	Inputs	Result / purpose
get_space	Read	None	Organization and Space identity, description, folder mode, root directory ID, credential mode.
list_inbox	Read	query?, sort?, sources?, offset?, limit?	Pending Inbox documents, browser URLs, and sources.
search_files	Read	query?, sort?, tag_ids?, document_type_id?, property_filters?, offset?, limit?	Filed documents. Empty query lists them. Excludes Inbox documents, directories, and deleted files.
get_file	Read	file_id	Live file or directory metadata. Documents include version, MIME type, size, OCR availability, document type, direct/resolved Tags, and assigned field values.
read_file_text	Read	file_id, offset?, length?	Existing file-level OCR text with availability and continuation. Does not start OCR or supply historical-version text.
upload_file	Write	filename, content_base64	Upload one document to the bound Space's Inbox. Returns file ID, browser URL, name, size, and Inbox state.
download_file	Read	file_id, version_number?, offset?, length?	Original decrypted/decompressed bytes as base64, version and file metadata, and continuation.

Search sorts are newestFirst, oldestFirst, name, and rank. Tag filters use resolved Tags and combine with AND. Text, document-type, and field filters also combine with AND. Inbox source filters use the server's source names, including MCP for MCP uploads.

Text windows use Unicode-character offsets, default to 12,000 characters, and allow at most 50,000. OCR availability is explicit and can still be false after a successful upload.

Uploads require standard padded base64 and a nonempty file of at most 10 MiB decoded, further restricted by the installation's upload limit. The MCP HTTP request body is limited to 16 MiB. filename must be a basename, not a path. A conflicting live Inbox filename fails without overwrite or automatic renaming. Uploading a new version, URL import, and batch or streaming uploads are not tools in this catalog.

Downloads use byte offsets and return at most 1 MiB decoded per call, also the default length. At offset 0, omitting version_number selects the latest version. For continuation, pass the returned version number and next_offset so chunks remain on the same version. Reading at EOF returns an empty final chunk. Original-byte download does not use browser cookies or expose storage URLs.

Tool	Access	Inputs	Result / purpose
list_tags	Read	group_id?, offset?, limit?	Tags with type, grouping, and composition references.
list_properties	Read	offset?, limit?	Field definitions with type and unit.
list_document_types	Read	offset?, limit?	Document-type summaries.
get_document_type	Read	document_type_id	Document type with its Tag-group and field attributes.
assign_tag	Write	file_id, tag_id	Ensure a direct Tag assignment exists. Group Tags cannot be assigned.
unassign_tag	Write	file_id, tag_id	Remove a direct assignment. Resolved/inherited Tags may remain.
set_file_property	Write	file_id, property_id, exactly one typed value	Create or update a field value.
remove_file_property	Write	file_id, property_id	Remove a field assignment.
set_document_type	Write	file_id, document_type_id	Set the document type without toggling an existing selection off.
clear_document_type	Write	file_id	Clear the document type.

Explicit assignment and removal operations preserve the desired state on repetition. Setting a document type does not create field values or remove unrelated metadata.

Field type	Value input	Format
Text	text_value	String, including an explicit empty string
Number	number_value	Integer
Money	money_minor_units	Integer minor units, for example 12345 for 123.45 with a two-decimal currency unit
Date	date_value	YYYY-MM-DD
Checkbox	checkbox_value	Boolean

The field definition supplies the type and unit. Exactly one matching value is required. Omitted/null values differ from empty text, zero, and false. Integers must fit the JSON safe-integer range and storage limits.

search_files accepts up to 32 property_filters. Each has property_id, operator, and the matching typed value input from the table above.

Type	Operators
Text	equals, contains, starts_with (case-insensitive)
Number, Money, Date	equals, greater_than, less_than, greater_than_or_equal, less_than_or_equal, between
Checkbox	equals, is_checked

An inclusive between also requires end_number_value, end_money_minor_units, or end_date_value with ordered bounds. False Checkbox conditions include documents without that field assignment. Text filter values are limited to 1,000 characters. Invalid conditions fail rather than being silently ignored.

Example tools/call parameters for filed invoices in a date range:

{
  "name": "search_files",
  "arguments": {
    "document_type_id": "<invoice-document-type-id>",
    "property_filters": [{
      "property_id": "<invoice-date-field-id>",
      "operator": "between",
      "date_value": "2026-09-01",
      "end_date_value": "2026-09-30"
    }],
    "limit": 50
  }
}

Replace the example IDs with values discovered through the metadata tools.

Tool	Access	Inputs	Result / purpose
list_directory	Read	directory_id?, offset?, limit?	Immediate children of a directory. Defaults to the Space root.
create_directory	Write	parent_directory_id, name	Create a filing folder.
file_inbox_document	Write	file_id, destination_directory_id, filename?, new_directory_name?	File an Inbox document and mark it done, optionally renaming it or creating a destination child folder.
mark_inbox_file_done	Write	file_id	Complete an Inbox document without moving it, including in non-folder Spaces.
rename_file	Write	file_id, new_filename	Rename an already-filed document or ordinary directory.
move_file	Write	file_id, destination_directory_id, filename?, new_directory_name?	Move an already-filed document or directory, optionally into a new child folder.

Directory creation, folder filing, and movement require folder mode. Inbox completion requires a live Inbox document. Standalone rename/move operate on filed entries, not the Space root or Inbox items. Existing collision and cycle checks apply. Filing and organization retain document identity, metadata, versions, and note history.

All tools in the following table require write access. Names and field units are limited to 300 Unicode characters. In-use definitions cannot be deleted by clearing their dependencies automatically.

Tool	Inputs	Result / purpose
create_tag	name, type, group_id?	Create a Simple, Group, or Super (composed) Tag.
edit_tag	tag_id, name	Rename a Tag.
delete_tag	tag_id	Delete an unused Tag.
create_and_assign_tag	file_id, name, type, group_id?	Create an assignable Tag and assign it atomically.
move_tag_to_group	tag_id, group_id?	Move into a group. Omit the group to remove grouping. Groups cannot be nested.
assign_sub_tag	super_tag_id, sub_tag_id	Add a simple Tag to a composed Tag.
unassign_sub_tag	super_tag_id, sub_tag_id	Remove a simple Tag from a composed Tag.
create_property	name, type, unit?	Create a Text, Number, Money, Date, or Checkbox field.
edit_property	property_id, name, unit?	Edit name/unit. Omitted unit is preserved, empty string clears it. Field type cannot change.
delete_property	property_id	Delete an unused field.
create_document_type	name	Create a document type.
rename_document_type	document_type_id, name	Rename a document type.
delete_document_type	document_type_id	Delete an unused document type.
create_document_type_tag_attribute	document_type_id, tag_id, name, is_name_giving?	Add a Tag-group attribute.
edit_document_type_tag_attribute	document_type_id, tag_id, name, is_name_giving	Edit a Tag-group attribute.
create_document_type_property_attribute	document_type_id, property_id, is_name_giving?	Add a field attribute.
edit_document_type_property_attribute	document_type_id, property_id, is_name_giving	Edit a field attribute's name-giving state.
delete_document_type_attribute	document_type_id, exactly one of tag_id or property_id	Remove an attribute.

Attribute references use a document-type ID paired with a Tag-group or field ID. No separate attribute ID is needed. Attribute edit calls require is_name_giving explicitly, including false. Attribute mutations return the updated document type.

Tool	Access	Inputs	Result / purpose
list_document_type_templates	Read	None	Available library keys and localized names.
import_document_types	Write	template_keys	Import 1–64 advertised template keys into a Space with no metadata.

Unknown template keys fail before import. Discover valid keys first.

Tool	Access	Inputs	Result / purpose
list_document_notes	Read	file_id, show_history?, offset?, limit?	Current notes, optionally history, with 1,000-character previews.
get_document_note	Read	file_id, note_id, offset?, length?	Note body window, attribution, timestamps, and continuation.
create_document_note	Write	file_id, title, body	Create an authored note. Repeated creation creates another note.
edit_document_note	Write	file_id, note_id, title, body	Edit a current note under existing author/owner permissions.
replace_document_note	Write	file_id, note_id, title, body	Create a successor and retain the predecessor in history.
delete_document_note	Write	file_id, note_id	Remove a current note into read-only history.

Titles are limited to 300 characters and new/edited bodies to 50,000. Body reads use character offsets, default to 12,000 characters, and allow at most 50,000. Every note selector is paired with its file ID. The reserved legacy selector addresses a document's legacy note, not a public note ID. Listing includes a separate legacy_note on page zero when present.

Write access alone does not grant permission to edit another author's note. Historical notes and notes in Trash are read-only. Returned can_change reflects the credential mode and the model's permissions.

Authentication failures return HTTP 401/403 without a sign-in redirect. Malformed JSON-RPC, unsupported methods, and schema errors follow MCP protocol handling. Tool operation errors use isError with a stable code and safe message, such as invalid_input, forbidden, not_found, conflict, limit_exceeded, or internal_error.

The catalog does not include account administration, Space membership management, Trash listing/restoration, duplicate discovery, version listing/merging, archive extraction, or OCR/preview retry. Use tools/list on your installation for the authoritative tool names and input schemas.

Reference for SimpleDMS 1.18.0, 1 October 2026.

• Connect AI assistants to SimpleDMS
• Set up MCP in SimpleDMS
• SimpleDMS MCP source
• Model Context Protocol specification