Connect an MCP client

Suchi ships an MCP (Model Context Protocol) adapter that exposes the REST surface as tools an LLM agent can call. Eight tools total — search_documents, get_document, list_inbox, resolve_approval_task, create_share_link, list_custom_fields, set_custom_field, clear_custom_field. See MCP reference for the tool schemas. This guide wires the adapter into three common runtimes. The pattern is the same everywhere: a subprocess spoken over stdio (or a Streamable HTTP endpoint) with SUCHI_URL + SUCHI_TOKEN in the environment. One adapter uses one token bound to one filing system. Select that system when minting the token; ordinary unqualified MCP requests then use its binding. There is no all-systems token or adapter routing option. Membership and document ACLs still apply; a scope alone does not grant access, and membership removal revokes credentials.

Prerequisites

A running suchi instance you can reach at some URL. Local dev (http://127.0.0.1:8000) works.

A scoped API token. Do NOT use an admin token. Generate one via:

# Copy the suchi_session cookie value from an authenticated browser session.
export SUCHI_SESSION='...'
curl -sS -X POST 'http://127.0.0.1:8000/api/tokens/?system=S02' \
  -H "Content-Type: application/json" \
  -H "Cookie: suchi_session=$SUCHI_SESSION" \
  -d '{"name":"mcp-desktop","scopes":"documents:read,documents:write"}'
# → {"token":"...", "name":"mcp-desktop", "scopes":"..."}

Or exchange email and password directly:

curl -sS -X POST 'http://127.0.0.1:8000/api/token/?system=S02' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'

These examples assume S02 has already been introduced and the account can enter it. Omit ?system=S02 to target the original archive, including before introduction; omission never selects whichever system the browser last displayed. Every MCP action is attributed to the token’s owner in the audit log. A Read-only token supports search, document reads, and inbox inspection. Choose Read & write only when the client must resolve approvals, create share links, or set and clear custom-field values.

The suchi binary somewhere on PATH, or the shipped suchi-mcp symlink (the binary responds to argv[0] rewrite so command: "suchi-mcp" in a config stays clean).

Claude Desktop

Config lives at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Add a mcpServers entry:

{
  "mcpServers": {
    "suchi": {
      "command": "suchi-mcp",
      "env": {
        "SUCHI_URL": "http://127.0.0.1:8000",
        "SUCHI_TOKEN": "0123abcd…"
      }
    }
  }
}

Restart Claude Desktop. In a new chat, the ”🔌” indicator should show suchi connected. Ask it “search my documents for ‘insurance’” — it will call search_documents under the hood. Rich metadata clauses use the same query language as browser search. For example, a client locating the owner’s Indian driving licence can call search_documents with:

field:Person=Ritesh field:Country=India tag:"type:driving-licence"

Those clauses are evaluated only inside the token’s bound filing system and normal ACL visibility. Use list_custom_fields when an agent does not know the exact controlled field name or choice. search_documents suppresses snippets for Confidential and Restricted documents. Treat the resulting title, ID, and local Suchi route as a safe locator boundary. Calling get_document returns extracted document content to the MCP client—and therefore to any model or remote runtime behind that client—even when the search snippet was empty. Do not fetch content merely to locate a sensitive document. If suchi-mcp isn’t on PATH, use the absolute path:

"command": "/usr/local/bin/suchi",
"args": ["mcp"]

Cursor

Cursor’s MCP config lives in Settings → Features → MCP or in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "suchi": {
      "command": "suchi-mcp",
      "env": {
        "SUCHI_URL": "http://127.0.0.1:8000",
        "SUCHI_TOKEN": "0123abcd…"
      }
    }
  }
}

Same shape as Claude Desktop. Restart Cursor; the tools appear in the Composer.

Remote MCP runtimes (Streamable HTTP)

For runtimes that connect over HTTP instead of stdio — an agent-framework running on a different host, a shared team-wide tool broker — launch the adapter with --http:

suchi mcp --http 127.0.0.1:7000 \
  --url   http://127.0.0.1:8000 \
  --token 0123abcd…

Point the runtime at http://<host>:7000. Two things to know:

The --token flag is baked into the process’s memory for the lifetime of the run — every tool call is attributed to that token’s owner and bound filing system. To use different credentials or systems, run a separate adapter per caller/system.
The MCP HTTP listener has no separate auth of its own. Restrict access to port 7000 with your usual mechanism (VPN, firewall rule, Tailscale, reverse-proxy with basic auth). Suchi’s MCP surface is agent-facing, not internet-facing.

Verifying the connection

Ask the MCP client to call list_inbox or search_documents and inspect its returned result in the token’s bound system. Client startup behavior varies; do not rely on an automatic first tool call. Suchi’s access logs (journalctl -u suchi or docker logs -f suchi) can help correlate route, status and request ID. Query text, credentials and document evidence are not diagnostic log fields. If you see 401 unauthorized, check the token and environment; revocation or account disablement also prevents authentication. A 403 can mean a missing scope or capability: grant only what the requested operation needs. An unavailable object/system is a 404, not an invitation to retry in another archive. Create a new token after an administrator restores membership; old credentials do not revive.

Revoking access

Token management is session-only. Use Settings in the web app or an authenticated browser/OIDC session; the MCP token cannot list or revoke tokens itself. The commands below assume SUCHI_SESSION contains the signed-in browser’s suchi_session cookie value.

# List your tokens with the session cookie.
curl -sS 'http://127.0.0.1:8000/api/tokens/?system=S02' \
  -H "Cookie: suchi_session=$SUCHI_SESSION" | jq

# Revoke by id.
curl -sS -X DELETE 'http://127.0.0.1:8000/api/tokens/7?system=S02' \
  -H "Cookie: suchi_session=$SUCHI_SESSION"

Revocation is immediate. Subsequent requests carrying the revoked token fail authentication.

Not covered here

OAuth-scoped agent flows — suchi’s tokens are bearer tokens, not OAuth. If you need OAuth resource-server semantics, front suchi with an OAuth gateway.
Multi-tenant MCP brokers — one adapter, one token. For per-user tokens on a shared runtime, run N adapters or wire the runtime to pass the token per-request (a shape not yet supported on the adapter side).

MCP reference — full tool schemas.
External app via API token — same token flow, non-MCP consumer.

Overview

Getting started

Reference

Concepts

Operations

Guides

Development

Alternatives

Connect an MCP client

Prerequisites

Claude Desktop

Cursor

Remote MCP runtimes (Streamable HTTP)

Verifying the connection

Revoking access

Not covered here

​Prerequisites

​Claude Desktop

​Cursor

​Remote MCP runtimes (Streamable HTTP)

​Verifying the connection

​Revoking access

​Not covered here

Prerequisites

Claude Desktop

Cursor

Remote MCP runtimes (Streamable HTTP)

Verifying the connection

Revoking access

Not covered here