Skip to main content
suchi mcp runs a thin Model Context Protocol adapter over the existing HTTP API. Tool calls use an ordinary Suchi token, object permissions, and audit path; the MCP process does not bypass application authorization. The token binds one filing system as its default and ceiling. Ordinary unqualified MCP calls therefore stay there, including search, tasks and shares; membership and document ACLs still apply. A different system needs a new bound token. Removing membership revokes the credential and re-adding it does not revive it.

​
Configure a local client

Docker images also provide suchi-mcp as a symlink to the same binary. Use a dedicated user and the minimum token scopes the client needs, not an administrator token. --url and --token override SUCHI_URL and SUCHI_TOKEN. The adapter never follows HTTP redirects, so it cannot forward its token to a redirect target. API responses must be bounded, valid application/json; redirects, unexpected content types, and malformed or oversized bodies fail closed. Failures expose the operation, HTTP status and safe error code when available; request queries, response bodies and transport diagnostics are not copied into tool errors. A transport failure means the configured server could not be reached; verify its address and connectivity before retrying.

​
Transports

The listener has no separate client authentication: every caller can exercise the Suchi token held by that adapter process. Bind to loopback by default. For remote use, expose it only through a VPN, firewall rule, or TLS reverse proxy that authenticates callers.

​
Tools

​
search_documents

Calls ranked GET /api/search/ with the same query language as the web app. Matching, BM25, recency, snippets, errors, and ACLs are not reimplemented by MCP; see Search architecture: MCP.
The query can combine free text with field:, has-field:, tag:, jd:, sensitivity:, and the other operators documented in the shared query language. Exact custom-field clauses use the definition’s name and typed value; call list_custom_fields first when the schema is not known.
  • query: required string
  • page_size: optional integer, default 10 and maximum 25
Results include document IDs, titles, snippets, rank, MIME type, and creation time after token-owner visibility and the token’s bound filing system are applied. Confidential and Restricted results have empty snippets. Requires documents:read.

​
get_document

Returns one document through GET /api/documents/{id} in the token’s bound filing system.
  • id: required document ID
The response includes extracted content and visible metadata. Calling this tool sends that content to the MCP client and to any model or remote runtime behind it; an empty sensitive-search snippet is not consent for that egress. Grant and invoke this tool only when the client is allowed to read archive text.

​
list_inbox

Returns up to 50 durable jobs and actionable approval tasks visible to the caller through GET /api/tasks/?limit=50. Approvals bound to trashed documents disappear; they can reappear after restoration only while the task and its run remain active. Requires documents:read for API-token callers.

​
resolve_approval_task

Resolves a task through POST /api/approvals/tasks/{id}/resolve. Requires documents:write for API-token callers.
  • task_id: required task ID
  • choice: required declared choice
Creates a link for 1 to 200 live documents in the token’s bound system through POST /api/share_links/. The creator must own each document or be an administrator, in addition to system entry. Requires documents:write for API-token callers and the share-links capability for non-admin users; mere view permission is insufficient.
  • doc_ids: required document ID array
  • label: optional label
  • visibility: required network or public
  • expires_in_sec: optional for Network links; Public links require 1–31,536,000 seconds
  • password: optional recipient password
The response contains an absolute /s/<token> URL. Network links use PUBLIC_URL; Public links use the configured SHARE_PUBLIC_URL and fail while public ingress is unavailable.

​
list_custom_fields

Lists custom-field definitions in the token’s bound system through GET /api/custom_fields/?page_size=500: ID, name, data_type, and type options such as select choices. A documentlink field is a named relationship to another document. Requires documents:read.

​
set_custom_field

Writes one value through PUT /api/documents/{id}/custom_fields/{field} and replaces any existing value. Requires documents:write.
  • document_id: required source document ID
  • field: required exact field name or numeric ID in the bound system
  • value: required typed value; for documentlink, the target document ID
Suchi applies the same validation and permission checks as Document Detail. A link requires change permission on the source and view permission on the live target; a self-link, a link inside one version history, or a trashed, hidden or missing document is refused. A link target must be a positive whole number: fractional, negative and zero IDs are rejected rather than rounded or treated as removal. A null or blank value is refused; use clear_custom_field. Values belong to one exact version. A replacement version starts without them, and a link keeps naming the version it was written to, so agents should link the current version that search_documents returns. The tool returns {"document_id":…,"field":…,"status":"set"}.

​
clear_custom_field

Removes one value, including a link, through DELETE /api/documents/{id}/custom_fields/{field}. Takes document_id and field; requires documents:write.

​
Current limits

MCP v0.1 does not expose arbitrary document mutation, raw document listing, MCP Resources, or bulk maintenance operations. Apart from resolving approvals, custom-field values and document links are the only document metadata it changes. It cannot read Documents linking to this version; outgoing links appear in get_document. Add server behavior to the REST API first; MCP tools should remain curated adapters rather than a second business-logic surface. See Connect an MCP client for client-specific examples and API for the underlying endpoint contracts.