> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suchi.page/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Expose a scoped subset of Suchi's API to MCP-capable clients.

`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

```json theme={null}
{
  "mcpServers": {
    "suchi": {
      "command": "suchi",
      "args": ["mcp"],
      "env": {
        "SUCHI_URL": "http://127.0.0.1:8000",
        "SUCHI_TOKEN": "<scoped API token>"
      }
    }
  }
}
```

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

| Invocation | Transport | Typical use |
| - | - | - |
| `suchi mcp` | stdio | Local desktop and editor clients |
| `suchi mcp --http 127.0.0.1:8100` | Streamable HTTP | Remote runtimes and inspectors through a protected network path |

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](https://docs.suchi.page/query-language.md)
as the web app. Matching, BM25, recency, snippets, errors, and ACLs are not
reimplemented by MCP; see [Search architecture: MCP](https://docs.suchi.page/search.md#mcp).

```text theme={null}
field:Person=Ritesh field:Country=India tag:"type:driving-licence"
```

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

### `create_share_link`

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](https://docs.suchi.page/guides/mcp-connect.md) for client-specific examples
and [API](https://docs.suchi.page/api.md) for the underlying endpoint contracts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.