Sutram MCP Server Guide

Version: 0.113.0 Date: 2026-08-20 Status: In production

---

Overview

This is the tool reference guide for the tools exposed by the Sutram MCP server. Once connected, your AI assistant can browse folders, upload files, add web/video/audio links, manage structured records and metadata, build the wiki / knowledge graph, run governance workflows (Document Classes), version files, take part in the project chat, and interact with comments — all with proper authentication and permissions.

How to connect: this document covers what each tool does. To connect Sutram to Claude (or to another MCP client) — via the OAuth connector or the API-key bridge — see Connecting Sutram to Claude.

Plan requirement: MCP access requires the Pro or higher plan. Viewers connect with a read-only surface (content-write tools are hidden and denied; comments and chat remain available).

---

Available Tools

Once connected, your AI assistant has access to these tools. You can also obtain this list programmatically by sending the standard MCP tools/list request to the server endpoint.

Quick Reference (A–Z)

#	Tool	Category	Description
1	sutram_add_enum_values	Schema	Adds new values to an existing enum metadata definition
2	sutram_bulk_create_file_links	File Links	Creates file links in bulk from a source folder to a target folder
3	sutram_cancel_checkout	Versioning	Cancels the checkout without uploading changes
4	sutram_checkin_file	Versioning	Releases a file from checkout (check-in)
5	sutram_checkout_file	Versioning	Checks out a file for exclusive editing
6	sutram_confirm_upload	Content	Upload step 2: confirms the file was uploaded to S3
7	sutram_create_audio_link	Content	Creates an audio link (Spotify, SoundCloud, etc.)
8	sutram_create_comment	Comments	Creates a file-level or markdown comment on a content item
9	sutram_create_document	Governance	Creates a governed document (family + 1st version) in a Document Class
10	sutram_create_document_version	Versioning	Creates a new revision of a governed document
11	sutram_create_documents	Governance	Batch-creates several governed documents of the same Class
12	sutram_create_file_link	File Links	Creates a file link (symbolic reference) to an existing file
13	sutram_create_folder	Folders	Creates a new folder or nested path
14	sutram_create_new_version	Versioning	Creates a new version from a published file
15	sutram_create_record	Records	Creates a new record in a category
16	sutram_create_video_link	Content	Creates a video link (YouTube, Vimeo, etc.)
17	sutram_create_web_link	Content	Creates a web link with an automatically fetched title
18	sutram_create_wiki_node	Wiki	Creates a wiki node (entity/concept) that [[slug]] mentions reference
19	sutram_delete	Content	Deletes a content item or folder
20	sutram_delete_comment	Comments	Deletes a comment and all its replies
21	sutram_delete_metadata	Schema	Deletes a metadata definition
22	sutram_delete_record	Records	Deletes a record
23	sutram_delete_record_category	Schema	Deletes a record category
24	sutram_delete_wiki_node	Wiki	Deletes (soft-delete) a wiki node
25	sutram_disable_versioning	Versioning	Converts the file back to a reference (read-only)
26	sutram_enable_versioning	Versioning	Converts a reference file to editable
27	sutram_force_release_lock	Versioning	Forcibly releases another user's checkout (owner only)
28	sutram_get_backlinks	Wiki	Lists an item's backlinks (who mentions it via [[slug]])
29	sutram_get_chat_thread	Chat	Gets a chat message with its reply thread
30	sutram_get_chat_unread_count	Chat	Returns how many chat messages have not yet been read
31	sutram_get_comment_thread	Comments	Gets a comment with its full reply thread
32	sutram_get_folder	Folders	Returns the contents of a folder
33	sutram_get_item	Content	Gets full details and a download URL for a content item
34	sutram_get_item_tag_keys	Tags	Returns all distinct tag keys used on content items
35	sutram_get_metadata_definitions	Schema	Returns all metadata field definitions
36	sutram_get_outgoing_mentions	Wiki	Lists the [[slug]] mentions leaving a source (resolved or pending)
37	sutram_get_record_categories	Schema	Returns all record categories
38	sutram_get_record_category_detail	Schema	Returns a category with resolved metadata (and the lifecycle, if governed)
39	sutram_get_tag_keys	Tags	Returns all distinct tag keys used on folders
40	sutram_get_wiki_node	Wiki	Returns a wiki node by id or slug, with synthesis and full text
41	sutram_graduate_document_class	Governance	Graduates a record category into a governed Document Class
42	sutram_grant_class_role	Governance	Grants a class role to an active project member, optionally scoped by metadata
43	sutram_list_chat_messages	Chat	Lists the project chat messages
44	sutram_list_class_grants	Governance	Lists the class-role grants of a Document Class (who holds which role, with scope)
45	sutram_list_comments	Comments	Lists all top-level comments on a content item
46	sutram_list_document_classes	Governance	Lists the accessible Document Classes
47	sutram_list_file_links_for_source	File Links	Lists all file links pointing to a source file
48	sutram_list_file_links_in_folder	File Links	Lists file links in a folder with source-file details
49	sutram_list_governed_documents	Governance	Lists the governed documents of a Document Class
50	sutram_list_versions	Versioning	Lists all versions of a file
51	sutram_mark_chat_visited	Chat	Marks the chat as read (resets the unread counter)
52	sutram_move_contents	Folders	Moves all contents of one folder to another
53	sutram_move_item	Content	Moves a single content item to another folder
54	sutram_patch_record_metadata	Records	Updates specific fields of a record (merge), preserving the rest
55	sutram_project_info	Project	Returns the project name, description, and settings
56	sutram_publish_version	Versioning	Publishes a draft file, creating a version snapshot
57	sutram_remove_enum_values	Schema	Removes values from an enum metadata definition
58	sutram_rename	Content	Renames a content item or folder
59	sutram_reply_to_chat_message	Chat	Replies to a top-level chat message
60	sutram_reply_to_comment	Comments	Replies to an existing top-level comment
61	sutram_request_upload	Content	Upload step 1: returns a presigned S3 PUT URL
62	sutram_resolve_comment	Comments	Resolves or reopens a comment thread
63	sutram_resolve_slug	Discovery	Resolves a [[slug]] mention slug to the item it points to
64	sutram_revert_document_class	Governance	Reverts a Document Class to a plain record category
65	sutram_revoke_class_role	Governance	Revokes one class-role grant (user + role) in a Document Class
66	sutram_search_folders	Tags	Searches folders by tag (single condition or AND conditions)
67	sutram_search_items	Tags	Searches content items by tag
68	sutram_search_wiki	Wiki	Full-text search over the wiki content (from a question)
69	sutram_search_wiki_nodes	Wiki	Lists/filters wiki nodes by name or category
70	sutram_send_chat_message	Chat	Posts a new message to the project chat
71	sutram_set_document_class_lifecycle	Governance	Sets the full lifecycle of a Document Class
72	sutram_set_folder_tags	Tags	Sets key-value tags on a folder
73	sutram_set_item_tags	Tags	Sets key-value tags on a content item
74	sutram_set_wiki_relation_labels	Wiki	Sets the wiki relation vocabulary (passive→active labels)
75	sutram_sync_wiki_source	Wiki	Populates a mirror node's source_text from the record's file
76	sutram_transition_document	Governance	Triggers a lifecycle transition on a governed document
77	sutram_undo_checkin	Versioning	Undoes the last check-in, restoring the previous version
78	sutram_update_record	Records	Replaces a record's metadata
79	sutram_update_wiki_node	Wiki	Updates a wiki node (name, category, body, typed relations)
80	sutram_upload_modified_file	Versioning	Replaces the file content during checkout
81	sutram_upsert_metadata	Schema	Creates or updates a metadata field definition
82	sutram_upsert_record_category	Schema	Creates or updates a record category

Categories: Project (1) · Discovery (1) · Folders (3) · Content (9) · File Links (4) · Tags (6) · Versioning (12) · Comments (6) · Schema (9) · Records (4) · Wiki (10) · Chat (6) · Governance (11)

---

The sections below describe each tool in detail, organized by functionality.

sutram_project_info

Returns information about the current project.

Parameters: None

Example response:

{
  "project": {
    "id": "a1b2c3d4-...",
    "name": "Construction Site Alpha",
    "description": "Main project documentation",
    "your_role": "member",
    "created_at": "2026-01-15T10:00:00Z"
  }
}

---

sutram_get_folder

Browses the contents of a folder (subfolders, files, and links). Omit folder_id to list the contents of the root.

Parameters:

Parameter	Type	Required	Description
folder_id	string	No	Folder UUID. Omit for the root.

Example response:

{
  "folder": {
    "id": null,
    "name": "Root",
    "path": "/"
  },
  "contents": [
    {
      "type": "folder",
      "id": "f1a2b3c4-...",
      "name": "Reports",
      "tags": {"category": "monthly", "department": "engineering"}
    },
    {
      "type": "file",
      "id": "d5e6f7a8-...",
      "name": "site-plan.pdf",
      "content_type": "application/pdf",
      "size": 2450000,
      "filename": "site-plan.pdf"
    },
    {
      "type": "web_link",
      "id": "a1b2c3d4-...",
      "name": "Project Wiki",
      "url": "https://wiki.example.com/project",
      "favicon_url": "https://wiki.example.com/favicon.ico"
    },
    {
      "type": "video_link",
      "id": "e5f6a7b8-...",
      "name": "Site walkthrough",
      "url": "https://www.youtube.com/watch?v=abc123",
      "platform": "youtube",
      "thumbnail_url": "https://img.youtube.com/vi/abc123/hqdefault.jpg"
    },
    {
      "type": "audio_link",
      "id": "c9d0e1f2-...",
      "name": "Meeting recording",
      "url": "https://open.spotify.com/episode/xyz",
      "platform": "spotify",
      "artist_or_author": "Team Alpha"
    }
  ]
}

---

sutram_create_folder

Creates a new folder. Supports creating nested hierarchies in a single call.

Parameters:

Parameter	Type	Required	Description
name	string	Yes*	Folder name (to create a single folder)
path	string	Yes*	Slash-separated path for nested creation (e.g., "A/B/C")
parent_folder_id	string	No	Parent folder UUID. Omit for the root level.
tags	object	No	Free-form key-value tags (e.g., {"patient": "John", "exam_type": "USG"}). When using path, tags are applied only to the leaf (deepest) folder.

*Use name (single folder) or path (nested hierarchy), not both.

Nested creation: When using path, intermediate folders are created automatically. If any folder in the path already exists, it is reused — the operation is idempotent.

Example — single folder:

{ "name": "Reports", "parent_folder_id": "f1a2b3c4-..." }

Example — nested hierarchy with tags:

{
  "path": "Dr. Decio Mion Junior/USG ABDOME TOTAL/2024-12-12",
  "tags": {"patient": "João Silva", "exam_type": "USG ABDOME TOTAL", "year": "2024"}
}

This creates three folders in one call and returns the deepest one (2024-12-12) with the specified tags.

---

sutram_request_upload

Step 1 of the direct upload flow. Validates the file and returns a presigned S3 PUT URL. The file is uploaded directly to S3 by the client — no data passes through Sutram's web servers.

Parameters:

Parameter	Type	Required	Description
filename	string	Yes	Filename with extension (e.g., report.pdf)
file_size	integer	Yes	File size in bytes
content_type	string	No	MIME type. Auto-detected from the extension if omitted.
folder_id	string	No	Target folder UUID. Omit for the root.

Example response:

{
  "upload_url": "https://eikon-storage.s3.amazonaws.com/projects/.../files/abc123.pdf?X-Amz-...",
  "s3_key": "projects/a1b2c3d4-.../files/abc123.pdf",
  "file_id": "abc123-...",
  "folder_id": null,
  "expires_in": 900
}

---

sutram_confirm_upload

Step 2 of the direct upload flow. Call after the file has been uploaded to the presigned URL. Verifies that the S3 object exists, creates the file record, updates storage usage, and queues compression if applicable.

Parameters:

Parameter	Type	Required	Description
file_id	string	Yes	File UUID from sutram_request_upload
s3_key	string	Yes	S3 key from sutram_request_upload
filename	string	Yes	Original filename with extension
content_type	string	Yes	File MIME type
file_size	integer	Yes	File size in bytes
folder_id	string	No	Target folder UUID (must match the request)

Example response:

{
  "file": {
    "id": "abc123-...",
    "name": "report.pdf",
    "size": 2450000,
    "content_type": "application/pdf",
    "created_at": "2026-02-27T10:00:00Z"
  }
}

Full upload flow example:

# 1. Request upload (via MCP tool call)
#    → Returns upload_url, s3_key, file_id

# 2. Upload file directly to S3
curl -X PUT \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf \
  "https://eikon-storage.s3.amazonaws.com/projects/.../files/abc123.pdf?X-Amz-..."

# 3. Confirm upload (via MCP tool call)
#    → File record created, storage updated, web UI updates in real-time

---

sutram_create_web_link

Creates a web link in the project. Sutram automatically fetches the page title and favicon from the URL.

Parameters:

Parameter	Type	Required	Description
url	string	Yes	Web page URL (must be http or https)
name	string	No	Display name. Automatically fetched from the page title if omitted.
folder_id	string	No	Target folder UUID. Omit for the root.

Example response:

{
  "web_link": {
    "id": "a1b2c3d4-...",
    "name": "Sutram Documentation",
    "url": "https://docs.sutram.io",
    "favicon_url": "https://docs.sutram.io/favicon.ico",
    "fetched_title": "Sutram Documentation",
    "created_at": "2026-02-09T14:30:00Z"
  }
}

---

sutram_create_video_link

Creates a video link in the project. Supports YouTube, Vimeo, DailyMotion, Wistia, Loom, and TikTok. Automatically detects the platform and extracts the video ID from the URL.

Parameters:

Parameter	Type	Required	Description
url	string	Yes	Video URL (e.g., https://www.youtube.com/watch?v=...)
name	string	No	Display name. Defaults to the URL if omitted.
folder_id	string	No	Target folder UUID. Omit for the root.

Example response:

{
  "video_link": {
    "id": "e5f6a7b8-...",
    "name": "Project overview",
    "url": "https://www.youtube.com/watch?v=abc123",
    "platform": "youtube",
    "video_id": "abc123",
    "thumbnail_url": "https://img.youtube.com/vi/abc123/hqdefault.jpg",
    "created_at": "2026-02-09T14:30:00Z"
  }
}

---

sutram_create_audio_link

Creates an audio link in the project. Supports Spotify, SoundCloud, Apple Podcasts, and others. Automatically detects the platform and extracts the audio ID from the URL.

Parameters:

Parameter	Type	Required	Description
url	string	Yes	Audio content URL (e.g., https://open.spotify.com/track/...)
name	string	No	Display name. Defaults to the URL if omitted.
folder_id	string	No	Target folder UUID. Omit for the root.

Example response:

{
  "audio_link": {
    "id": "c9d0e1f2-...",
    "name": "Weekly standup recap",
    "url": "https://open.spotify.com/episode/xyz789",
    "platform": "spotify",
    "artist_or_author": "Team Alpha",
    "thumbnail_url": "https://i.scdn.co/image/abc",
    "created_at": "2026-02-09T14:30:00Z"
  }
}

---

sutram_create_file_link

Creates a file link (symbolic reference) to an existing file in the project. The link appears as a read-only reference without duplicating storage or versioning. The source must be a file (not a link or another file link). If the source file is deleted, all of its file links are removed automatically.

Parameters:

Parameter	Type	Required	Description
source_content_item_id	string	Yes	UUID of the source file's content item to link to
name	string	No	Display name (defaults to the source file's name)
folder_id	string	No	Target folder UUID (omit for the root)
description	string	No	File link description

Example request:

{
  "source_content_item_id": "d5e6f7a8-...",
  "folder_id": "b2c3d4e5-...",
  "name": "Lab results (link)"
}

Example response:

{
  "file_link": {
    "id": "f1a2b3c4-...",
    "name": "Lab results (link)",
    "source_content_item_id": "d5e6f7a8-...",
    "folder_id": "b2c3d4e5-...",
    "created_at": "2026-03-14T10:00:00Z"
  }
}

---

sutram_bulk_create_file_links

Creates file links in bulk for all files (or a filtered subset) in a source folder, placing them in a target folder. Automatically skips files that already have a link in the target folder (deduplication). Ideal for workflows such as linking multiple exam files to a centralized reports folder.

Parameters:

Parameter	Type	Required	Description
source_folder_id	string	Yes	UUID of the source folder containing the files to link
target_folder_id	string	Yes	UUID of the target folder where the file links will be created
name_pattern	string	No	Substring filter (case-insensitive) on the source file names. Only matching files are linked.
recursive	boolean	No	Include files from subfolders of the source folder (default: false)

Example request:

{
  "source_folder_id": "a1b2c3d4-...",
  "target_folder_id": "e5f6a7b8-...",
  "name_pattern": "laudo",
  "recursive": true
}

Example response:

{
  "created": 5,
  "skipped": 2,
  "file_links": [
    {
      "id": "f1a2b3c4-...",
      "name": "laudo-hemograma.pdf",
      "source_content_item_id": "d5e6f7a8-...",
      "folder_id": "e5f6a7b8-..."
    },
    {
      "id": "f2b3c4d5-...",
      "name": "laudo-raio-x.pdf",
      "source_content_item_id": "c4d5e6f7-...",
      "folder_id": "e5f6a7b8-..."
    }
  ]
}

Tip: Running the same command again will skip all previously linked files ("created": 0, "skipped": 7), making it safe to re-run.

---

sutram_list_file_links_for_source

Lists all file links pointing to a given source file. Answers the question: "where is this file referenced?" Returns each link with its folder path.

Parameters:

Parameter	Type	Required	Description
source_content_item_id	string	Yes	UUID of the source file's content item

Example request:

{
  "source_content_item_id": "d5e6f7a8-..."
}

Example response:

{
  "source": {
    "id": "d5e6f7a8-...",
    "name": "hemograma-completo.pdf",
    "type": "file"
  },
  "file_links": [
    {
      "id": "f1a2b3c4-...",
      "name": "hemograma-completo.pdf",
      "folder_id": "b2c3d4e5-...",
      "folder_path": "Pacientes/João Silva/Laudos",
      "created_at": "2026-03-14T10:00:00Z"
    },
    {
      "id": "f2b3c4d5-...",
      "name": "hemograma-completo.pdf",
      "folder_id": "c3d4e5f6-...",
      "folder_path": "Relatórios/Março 2026",
      "created_at": "2026-03-14T10:05:00Z"
    }
  ],
  "count": 2
}

---

sutram_list_file_links_in_folder

Lists all file links in a folder, enriched with source-file details (name, content type, size, folder path). Unlike sutram_get_folder, this provides complete information about the source file each link points to.

Parameters:

Parameter	Type	Required	Description
folder_id	string	No	Folder UUID (omit for the root)

Example request:

{
  "folder_id": "e5f6a7b8-..."
}

Example response:

{
  "folder_id": "e5f6a7b8-...",
  "file_links": [
    {
      "id": "f1a2b3c4-...",
      "name": "hemograma-completo.pdf",
      "created_at": "2026-03-14T10:00:00Z",
      "source": {
        "id": "d5e6f7a8-...",
        "name": "hemograma-completo.pdf",
        "content_type": "application/pdf",
        "file_size": 245760,
        "folder_path": "Exames/Laboratório"
      }
    },
    {
      "id": "f2b3c4d5-...",
      "name": "raio-x-torax.dcm",
      "created_at": "2026-03-14T10:05:00Z",
      "source": {
        "id": "c4d5e6f7-...",
        "name": "raio-x-torax.dcm",
        "content_type": "application/dicom",
        "file_size": 5242880,
        "folder_path": "Exames/Imagem"
      }
    }
  ],
  "count": 2
}

---

sutram_get_item

Gets full details of a content item by ID. For files, it returns metadata and a presigned download URL. For links (web, video, audio, file_link), it returns the URL, platform information, and metadata.

Parameters:

Parameter	Type	Required	Description
content_item_id	string	Yes	UUID of the content item

Example response (file):

{
  "id": "d5e6f7a8-...",
  "type": "file",
  "name": "site-plan",
  "description": null,
  "tags": {"category": "planta", "year": "2024"},
  "folder_id": "f1a2b3c4-...",
  "created_at": "2026-01-20T10:00:00Z",
  "filename": "site-plan.pdf",
  "file_size": 2450000,
  "content_type": "application/pdf",
  "version": 1,
  "download_url": "https://storage.example.com/projects/.../site-plan.pdf?X-Amz-..."
}

Example response (web link):

{
  "id": "a1b2c3d4-...",
  "type": "web_link",
  "name": "Project Wiki",
  "description": null,
  "tags": {},
  "folder_id": null,
  "created_at": "2026-02-01T08:00:00Z",
  "url": "https://wiki.example.com/project",
  "fetched_title": "Project Wiki - Home",
  "fetched_description": "Documentation for the project",
  "favicon_url": "https://wiki.example.com/favicon.ico"
}

Example response (video link):

{
  "id": "e5f6a7b8-...",
  "type": "video_link",
  "name": "Site walkthrough",
  "description": null,
  "tags": {"topic": "neurologia"},
  "folder_id": "f1a2b3c4-...",
  "created_at": "2026-02-05T16:00:00Z",
  "url": "https://www.youtube.com/watch?v=abc123",
  "platform": "youtube",
  "video_id": "abc123",
  "thumbnail_url": "https://img.youtube.com/vi/abc123/hqdefault.jpg",
  "duration_seconds": null,
  "fetched_title": "Construction Site Alpha - Full Tour"
}

---

sutram_delete

Deletes a content item (file, web link, video link, audio link) or folder from the project.

Parameters:

Parameter	Type	Required	Description
item_id	string	Yes	UUID of the content item or folder
item_type	string	Yes	"content_item" or "folder". Use "content_item" for any content type (files, web links, video links, audio links).

---

sutram_rename

Renames a content item (file, web link, video link, audio link) or folder.

Parameters:

Parameter	Type	Required	Description
item_id	string	Yes	UUID of the content item or folder
item_type	string	Yes	"content_item" or "folder". Use "content_item" for any content type (files, web links, video links, audio links).
new_name	string	Yes	New name (for files, include the extension)

---

sutram_move_contents

Moves all contents (subfolders and files) from a source folder to a target folder. The source folder is emptied but not deleted. Name conflicts are handled automatically.

Parameters:

Parameter	Type	Required	Description
source_folder_id	string	Yes	UUID of the source folder to empty
target_folder_id	string	Yes	UUID of the target folder to receive the contents

Name-conflict handling: If a subfolder or file with the same name already exists in the target folder, Sutram automatically renames the moved item by adding a numeric suffix: Exams becomes Exams (1), report.pdf becomes report (1).pdf, and so on.

Validation rules:

• Source and target must be different folders
• The target cannot be a subfolder of the source (prevents circular moves)
• Both folders must exist in the current project

Example response:

{
  "moved": {
    "folders": 3,
    "content_items": 12
  },
  "renamed": {
    "folders": ["Exams (1)"],
    "files": ["report (1).pdf"]
  },
  "source_folder_id": "abc123-...",
  "target_folder_id": "def456-..."
}

---

sutram_move_item

Moves a single content item (file or link) to another folder. Name conflicts are handled automatically.

Parameters:

Parameter	Type	Required	Description
content_item_id	string	Yes	UUID of the content item to move
target_folder_id	string/null	No	Target folder UUID (null for the root)

Name-conflict handling: If a file with the same name already exists in the target folder, Sutram automatically renames the moved file by adding a numeric suffix: report.pdf becomes report (1).pdf, and so on.

Example response (no conflict):

{
  "moved": true,
  "renamed": false,
  "new_filename": null,
  "content_item": {
    "id": "abc123-...",
    "name": "report",
    "folder_id": "def456-..."
  }
}

Example response (with rename):

{
  "moved": true,
  "renamed": true,
  "new_filename": "report (1).pdf",
  "content_item": {
    "id": "abc123-...",
    "name": "report (1)",
    "folder_id": "def456-..."
  }
}

---

sutram_set_folder_tags

Sets free-form key-value tags on a folder. Replaces all existing tags. Send {} to clear all tags.

Parameters:

Parameter	Type	Required	Description
folder_id	string	Yes	Folder UUID
tags	object	Yes	Key-value tags to set. Send {} to clear all tags.

Limits: Maximum of 50 tags per folder. Key up to 100 characters, value up to 500 characters.

Semantics: This is a PUT operation — it replaces all existing tags. To add a tag without removing the others, first read the current tags (via sutram_get_folder), merge your changes, and then call sutram_set_folder_tags with the full set.

Example — set tags:

{
  "folder_id": "f1a2b3c4-...",
  "tags": {"patient": "João Silva", "exam_type": "USG", "year": "2024"}
}

Example — clear all tags:

{
  "folder_id": "f1a2b3c4-...",
  "tags": {}
}

Example response:

{
  "id": "f1a2b3c4-...",
  "name": "2024-12-12",
  "tags": {"patient": "João Silva", "exam_type": "USG", "year": "2024"}
}

---

sutram_search_folders

Searches folders by tag. Supports a single condition or multiple AND conditions. All matching is case-insensitive for keys and values. Values support substring matching (e.g., "orto" matches "Ortopedia"). Use folder_id to restrict the search to the descendants of a specific folder.

Parameters:

Parameter	Type	Required	Description
tag_name	string	No*	Tag key to search (single-condition mode). Case-insensitive.
tag_value	string	No	Value to match (single-condition mode). Substring matching, case-insensitive.
conditions	array	No*	Multiple AND conditions. Each object has key (required) and value (optional).
folder_id	string	No	Folder UUID to scope the search. Searches only the descendants of this folder.

*Use tag_name (single condition) or conditions (multiple AND conditions).

Search behavior:

• Key matching: Case-insensitive exact match ("Patient" matches "patient")
• Value matching: Case-insensitive substring match ("orto" matches "Ortopedia", "joão" matches "João Silva")
• No value: When the value is omitted, it matches any folder that has the key regardless of value
• Multiple conditions: All conditions must match (AND logic)

Example — find all folders with the "patient" tag:

{ "tag_name": "patient" }

Example — find folders for a specific patient (substring matching):

{ "tag_name": "patient", "tag_value": "joão" }

This matches folders where the "patient" tag contains "joão" (e.g., "João Silva", "João Pedro").

Example — AND search with multiple conditions:

{
  "conditions": [
    { "key": "patient", "value": "joão" },
    { "key": "exam_type", "value": "USG" }
  ]
}

This returns only folders that match both conditions.

Example — search only within a specific folder hierarchy:

{ "tag_name": "exam_type", "folder_id": "a1b2c3d4-..." }

Example response:

{
  "folders": [
    {
      "id": "f1a2b3c4-...",
      "name": "2024-12-12",
      "path": "/Dr. Decio Mion Junior/USG ABDOME TOTAL/2024-12-12",
      "tags": {"patient": "João Silva", "exam_type": "USG", "year": "2024"}
    }
  ],
  "count": 1
}

---

sutram_get_tag_keys

Returns all distinct tag keys used on folders in the project. Useful for discovering which tags are available before performing a search. Use folder_id to restrict to the descendants of a specific folder.

Parameters:

Parameter	Type	Required	Description
folder_id	string	No	Folder UUID to scope. Returns only keys from descendants of this folder.

Example — get all tag keys in the project:

{}

Example — get tag keys within a folder hierarchy:

{ "folder_id": "a1b2c3d4-..." }

Example response:

{
  "keys": ["exam_type", "patient", "specialty", "year"],
  "count": 4
}

---

sutram_set_item_tags

Sets free-form key-value tags on a content item. Replaces all existing tags. Send {} to clear all tags.

Parameters:

Parameter	Type	Required	Description
content_item_id	string	Yes	UUID of the content item
tags	object	Yes	Key-value tags to set. Send {} to clear all tags.

Limits: Maximum of 50 tags per item. Key up to 100 characters, value up to 500 characters.

Semantics: This is a PUT operation — it replaces all existing tags. To add a tag without removing the others, first read the current tags (via sutram_get_item), merge your changes, and then call sutram_set_item_tags with the full set.

Example — set tags:

{
  "content_item_id": "d5e6f7a8-...",
  "tags": {"category": "report", "year": "2024", "topic": "neurologia"}
}

Example — clear all tags:

{
  "content_item_id": "d5e6f7a8-...",
  "tags": {}
}

Example response:

{
  "id": "d5e6f7a8-...",
  "name": "site-plan",
  "tags": {"category": "report", "year": "2024", "topic": "neurologia"}
}

---

sutram_search_items

Searches content items by tag. Supports a single condition or multiple AND conditions. All matching is case-insensitive for keys and values. Values support substring matching (e.g., "neuro" matches "Neurologia"). Use folder_id to restrict the search to a specific folder, and type to filter by content type.

Parameters:

Parameter	Type	Required	Description
tag_name	string	No*	Tag key to search (single-condition mode). Case-insensitive.
tag_value	string	No	Value to match (single-condition mode). Substring matching, case-insensitive.
conditions	array	No*	Multiple AND conditions. Each object has key (required) and value (optional).
folder_id	string	No	Folder UUID to scope the search.
type	string	No	Content-type filter: "file", "file_link", "web_link", "video_link", "audio_link"

*Use tag_name (single condition) or conditions (multiple AND conditions).

Example — find all items with the "topic" tag:

{ "tag_name": "topic" }

Example — find items for a specific topic (substring matching):

{ "tag_name": "topic", "tag_value": "neuro" }

Example — AND search with multiple conditions:

{
  "conditions": [
    { "key": "topic", "value": "neuro" },
    { "key": "year", "value": "2024" }
  ]
}

Example — search only video links in a specific folder:

{ "tag_name": "topic", "folder_id": "f1a2b3c4-...", "type": "video_link" }

Example response:

{
  "items": [
    {
      "id": "d5e6f7a8-...",
      "type": "file",
      "name": "site-plan",
      "tags": {"topic": "neurologia", "year": "2024"},
      "folder_id": "f1a2b3c4-..."
    }
  ],
  "count": 1
}

---

sutram_get_item_tag_keys

Returns all distinct tag keys used on content items in the project. Useful for discovering which tags are available before performing a search. Use folder_id to restrict to a specific folder, and type to filter by content type.

Parameters:

Parameter	Type	Required	Description
folder_id	string	No	Folder UUID to scope.
type	string	No	Content-type filter: "file", "file_link", "web_link", "video_link", "audio_link"

Example — get all content tag keys in the project:

{}

Example — get tag keys only for video links:

{ "type": "video_link" }

Example response:

{
  "keys": ["category", "format", "topic", "year"],
  "count": 4
}

File Versioning

Sutram supports a complete versioning flow for files via MCP. This allows AI assistants to enable version control, check out files for exclusive editing, upload modifications, and publish versions.

Workflow

1. Enable versioning     →  sutram_enable_versioning
2. Check out file        →  sutram_checkout_file
3. Upload modification   →  sutram_request_upload + PUT to S3 + sutram_upload_modified_file
4. Check in file         →  sutram_checkin_file
5. Publish version       →  sutram_publish_version
6. Create new version    →  sutram_create_new_version  (starts new cycle at step 2)

Versioning Tools

Tool	Description	Permission
sutram_enable_versioning	Converts a reference file to editable (starts versioning)	Owner, Admin, Member
sutram_disable_versioning	Converts a file back to a reference (stops versioning)	Owner, Admin, Member
sutram_checkout_file	Checks out the file for exclusive editing	Owner, Admin, Member
sutram_checkin_file	Releases the checkout lock	Checkout user
sutram_cancel_checkout	Cancels the checkout without changes	Checkout user
sutram_force_release_lock	Forcibly releases another user's checkout	Owner, Admin
sutram_publish_version	Publishes a draft file, creating a version snapshot	Owner, Admin, Member
sutram_create_new_version	Starts a new version from a published file	Owner, Admin, Member
sutram_undo_checkin	Undoes the last check-in, restores the previous version	Last check-in user
sutram_list_versions	Lists all published versions with download URLs	Any participant
sutram_upload_modified_file	Replaces the file content during checkout	Checkout user

Parameters

All versioning tools require content_item_id (UUID of the content item).

sutram_upload_modified_file additionally requires:

Parameter	Type	Description
s3_key	string	S3 key from sutram_request_upload
file_name	string	Filename with extension
file_size	integer	File size in bytes
content_type	string	MIME type

Example: Complete Versioning Flow

// 1. Enable versioning on a file
→ sutram_enable_versioning { "content_item_id": "abc-123" }
← { "file": { "file_type": "editable", "lifecycle_status": "draft", "version": 1 } }

// 2. Check out the file
→ sutram_checkout_file { "content_item_id": "abc-123" }
← { "file": { "checked_out_by": "Alice", ... } }

// 3. Get presigned URL for the modified file
→ sutram_request_upload { "filename": "report_v2.pdf", "file_size": 5000 }
← { "upload_url": "https://s3...", "s3_key": "projects/.../file.pdf" }

// 4. PUT modified file to S3 (HTTP PUT to upload_url)

// 5. Upload the modification
→ sutram_upload_modified_file {
    "content_item_id": "abc-123",
    "s3_key": "projects/.../file.pdf",
    "file_name": "report_v2.pdf",
    "file_size": 5000,
    "content_type": "application/pdf"
  }

// 6. Check in the file
→ sutram_checkin_file { "content_item_id": "abc-123" }

// 7. Publish the version (owner only)
→ sutram_publish_version { "content_item_id": "abc-123" }
← { "file": { "lifecycle_status": "published", "version": 1 } }

// 8. List versions
→ sutram_list_versions { "content_item_id": "abc-123" }
← { "versions": [{ "version_number": 1, "download_url": "...", ... }], "count": 1 }

---

Record Categories and Records

Sutram supports structured records with metadata schemas and automatically generated slugs. This allows AI assistants to define metadata fields, create record categories, and manage records programmatically.

Plan requirement: The record and schema management tools require a plan with the Records feature enabled (Pro or higher). The read-only tools (sutram_get_metadata_definitions, sutram_get_record_categories, sutram_get_record_category_detail) are available on all plans.

Concepts

• Metadata definitions — Field schemas that define the types, labels, and allowed values for metadata fields (e.g., "language" as an enum with values "PT", "EN", "ES").
• Record categories — Templates that define which metadata fields a record uses, their order, how the number base is computed (computed_from), and how the slug (record name) is composed (slug_from).
• Records — Folders created with a category, validated metadata, and an automatically generated slug.

Slug Generation

Records have an automatically generated slug (used as the record name). The slug is built in two steps:

1. Number base — Determined by the computed_from entries on a computed metadata tag. This defines which field values form the uniqueness key for sequential numbering.
2. Slug composition — Determined by the slug_from entries on the category. This defines which field values (including the computed tag) make up the final slug.

Without slug_from (backward compatible): slug = number_base + separator + sequence_number (e.g., 0100-200-001).

With slug_from: the slug is composed from the referenced fields in order (e.g., MD-3010.95-0000-000-SWA-001).

Schema Tools

Tool	Description	Permission
sutram_get_metadata_definitions	Lists all metadata definitions	Any participant
sutram_get_record_categories	Lists all record categories	Any participant
sutram_get_record_category_detail	Category with resolved metadata (labels, types, allowed values)	Any participant
sutram_upsert_metadata	Creates or updates a metadata definition	Owner, Admin
sutram_delete_metadata	Deletes a metadata definition (fails if in use)	Owner, Admin
sutram_add_enum_values	Adds values to an enum definition (merges, deduplicates, sorts)	Owner, Admin
sutram_remove_enum_values	Removes values from an enum definition by code	Owner, Admin
sutram_upsert_record_category	Creates or updates a record category	Owner, Admin
sutram_delete_record_category	Deletes a record category	Owner, Admin

Record CRUD Tools

Tool	Description	Permission
sutram_create_record	Creates a record with category, metadata, and auto-generated slug	Owner, Admin, Member
sutram_update_record	Replaces all of a record's metadata (recalculates the slug if needed)	Owner, Admin, Member
sutram_patch_record_metadata	Updates specific fields of a record (merge), preserving the rest	Owner, Admin, Member
sutram_delete_record	Deletes a record and all its contents recursively	Owner, Admin, Member

sutram_get_metadata_definitions

Returns all of the project's metadata definitions. Each definition has a key and properties: label, type (text, enum, boolean, date, computed), and optionally values, depends_on, values_map.

Parameters: None

---

sutram_get_record_categories

Returns all of the project's record categories. Each category defines which metadata fields a record uses, slug configuration, and ordering.

Parameters: None

---

sutram_get_record_category_detail

Returns a record category with fully resolved metadata (labels, types, allowed values from the definitions). Use this to understand which fields are required before creating a record.

Parameters:

Parameter	Type	Required	Description
category_id	string	Yes	Record category ID

---

sutram_upsert_metadata

Creates or updates a metadata definition (field schema). For enum types, provide the full array of values. For large enums, prefer sutram_add_enum_values for incremental additions.

Parameters:

Parameter	Type	Required	Description
key	string	Yes	Unique key (snake_case, e.g., "specialty")
definition	object	Yes	Definition with label, type, and optional fields

Supported types: text, enum, boolean, date, computed.

Example — create a simple enum:

{
  "key": "language",
  "definition": {
    "label": "Language",
    "type": "enum",
    "values": [
      { "label": "Portuguese", "code": "PT" },
      { "label": "English", "code": "EN" }
    ]
  }
}

---

sutram_delete_metadata

Deletes a metadata definition. Fails if the definition is currently in use by any record category.

Parameters:

Parameter	Type	Required	Description
key	string	Yes	Key of the definition to delete

---

sutram_add_enum_values

Adds values to an existing enum metadata definition. New values are merged with the existing ones — duplicates (by code) are ignored. Values are sorted by code after merging. Use this instead of sutram_upsert_metadata when working with large enums to avoid sending the entire array of values.

Parameters:

Parameter	Type	Required	Description
key	string	Yes	Enum definition key
values	array	Yes	Array of {label, code} objects to add

Example — add values to an existing enum with more than 800 items:

{
  "key": "area_atividade",
  "values": [
    { "label": "Automação Industrial", "code": "0999" },
    { "label": "Telecomunicações", "code": "1050" }
  ]
}

Example response:

{
  "key": "area_atividade",
  "added": 2,
  "skipped_duplicates": 0,
  "total_values": 886
}

---

sutram_remove_enum_values

Removes values from an existing enum metadata definition by their codes.

Parameters:

Parameter	Type	Required	Description
key	string	Yes	Enum definition key
codes	array	Yes	Array of code strings to remove

Example:

{
  "key": "area_atividade",
  "codes": ["0999", "1050"]
}

Example response:

{
  "key": "area_atividade",
  "removed": 2,
  "not_found": 0,
  "total_values": 884
}

---

sutram_upsert_record_category

Creates or updates a record category. The metadata must reference existing definitions. Use computed_from on a metadata entry to define the number base (uniqueness). Use slug_from at the category level to define how the slug (record name) is composed.

Parameters:

Parameter	Type	Required	Description
category_id	string	Yes	Unique category ID (snake_case)
category	object	Yes	Category definition (see fields below)

Category fields:

Field	Type	Required	Description
name	string	Yes	Category display name
metadata	array	Yes	Array of metadata field references (see below)
slug_separator	string	No	Separator between slug parts (default: "-")
slug_from	array	No	Defines slug composition. Each entry has key and use ("code" or "label"). If omitted, slug = number_base + separator + sequence_number

Metadata entry fields:

Field	Type	Required	Description
key	string	Yes	Key of an existing metadata definition
required	boolean	No	Whether this field is required (default: false)
order	integer	No	Display order (0-based)
computed_from	array	No	For computed tags only. Defines the number base. Each entry has key and use ("code" or "label")
sequence_digits	integer	No	For computed tags only. Digits for the sequence number (2-4, default: 2)

Example — category with slug_from (N-1710 style):

{
  "category_id": "doc_tecnico_n1710",
  "category": {
    "name": "Technical Document N-1710",
    "metadata": [
      { "key": "language", "required": false, "order": 0 },
      { "key": "document_category", "required": true, "order": 1 },
      { "key": "installation", "required": true, "order": 2 },
      { "key": "activity_area", "required": true, "order": 3 },
      { "key": "service_class", "required": true, "order": 4 },
      { "key": "document_origin", "required": true, "order": 5 },
      {
        "key": "coded_number", "required": false, "order": 6,
        "computed_from": [
          { "key": "language", "use": "code" },
          { "key": "document_category", "use": "code" },
          { "key": "installation", "use": "label" },
          { "key": "activity_area", "use": "label" },
          { "key": "service_class", "use": "label" }
        ],
        "sequence_digits": 3
      }
    ],
    "slug_separator": "-",
    "slug_from": [
      { "key": "language", "use": "code" },
      { "key": "document_category", "use": "code" },
      { "key": "installation", "use": "label" },
      { "key": "activity_area", "use": "label" },
      { "key": "service_class", "use": "label" },
      { "key": "document_origin", "use": "label" },
      { "key": "coded_number", "use": "label" }
    ]
  }
}

In this example:

• Number base (from computed_from): MD-3010.95-0000-000 — determines sequential uniqueness
• Coded number: 001 (next available sequence)
• Slug (from slug_from): MD-3010.95-0000-000-SWA-001 — includes document_origin + sequence

Example — simple category without slug_from (backward compatible):

{
  "category_id": "exam",
  "category": {
    "name": "Medical Exam",
    "metadata": [
      { "key": "specialty", "required": true, "order": 0 },
      {
        "key": "exam_number", "order": 1,
        "computed_from": [
          { "key": "specialty", "use": "code" }
        ],
        "sequence_digits": 3
      }
    ],
    "slug_separator": "-"
  }
}

Without slug_from, the slug is automatically: {number_base}{separator}{sequence} (e.g., CARDIO-001).

---

sutram_delete_record_category

Deletes a record category.

Parameters:

Parameter	Type	Required	Description
category_id	string	Yes	ID of the category to delete

---

sutram_create_record

Creates a record with a category, validated metadata, and an auto-generated slug. The slug is computed from the category's slug_from definition, or from computed_from (number base) + separator + sequence number. Use sutram_get_record_category_detail first to see the required fields.

Parameters:

Parameter	Type	Required	Description
category_id	string	Yes	Record category ID
metadata	object	Yes	Key-value pairs matching the category's metadata fields
parent_folder_id	string	No	Parent folder UUID (omit for the root)
name	string	No	Custom name (defaults to the auto-generated slug)

Example:

{
  "category_id": "doc_tecnico_n1710",
  "metadata": {
    "language": "PT",
    "document_category": "Especificação",
    "installation": "3010.95",
    "activity_area": "0000",
    "service_class": "000",
    "document_origin": "SWA"
  }
}

The response includes the computed slug and sequence number:

{
  "record": {
    "id": "...",
    "name": "MD-3010.95-0000-000-SWA-001",
    "slug": "MD-3010.95-0000-000-SWA-001",
    "category": "doc_tecnico_n1710",
    "metadata": {
      "language": "PT",
      "document_category": "Especificação",
      "coded_number": "001",
      "slug": "MD-3010.95-0000-000-SWA-001",
      ...
    }
  }
}

---

sutram_update_record

Replaces the entire metadata map of a record with the supplied object. Recalculates the number base and slug when fields referenced by computed_from or slug_from are changed. To change only one field without rewriting the rest, use sutram_patch_record_metadata.

Parameters:

Parameter	Type	Required	Description
record_id	string	Yes	Record (folder) UUID
metadata	object	Yes	Full metadata map (replaces the previous one)
name	string	No	New name (optional)

---

sutram_patch_record_metadata

Updates one or more of a record's metadata fields by merging with the existing metadata (unlike sutram_update_record, which replaces the entire map). Provide only the keys you want to change; the rest remain intact. Set a key to null to remove it. If you change a field that does not compose the slug, the slug and sequence number remain unchanged; if you change a field that composes the slug, it is recalculated as in sutram_update_record.

Parameters:

Parameter	Type	Required	Description
record_id	string	Yes	Record (folder) UUID
metadata	object	Yes	Only the keys to set or remove (null removes), e.g., {"status": "approved"}
name	string	No	New name (optional; by default the name follows the recalculated slug only if it already mirrored it)

Example — change only one field:

{
  "record_id": "abc-123",
  "metadata": { "status": "approved" }
}

---

sutram_delete_record

Deletes a record and all its contents (subfolders and files) recursively. This action cannot be undone.

Parameters:

Parameter	Type	Required	Description
record_id	string	Yes	UUID of the record (folder) to delete

Example: Complete Records Flow

// 1. Create metadata definitions
→ sutram_upsert_metadata { "key": "language", "definition": { "label": "Language", "type": "enum",
    "values": [{"label": "PT", "code": "PT"}, {"label": "EN", "code": "EN"}] } }
→ sutram_upsert_metadata { "key": "area", "definition": { "label": "Area", "type": "enum",
    "values": [{"label": "Automação", "code": "0100"}, {"label": "Civil", "code": "0200"}] } }
→ sutram_upsert_metadata { "key": "origin", "definition": { "label": "Origin", "type": "text" } }
→ sutram_upsert_metadata { "key": "doc_number", "definition": { "label": "Number", "type": "computed" } }

// 2. Add more values to a large enum incrementally
→ sutram_add_enum_values { "key": "area", "values": [{"label": "Elétrica", "code": "0300"}] }

// 3. Create a record category with computed_from and slug_from
→ sutram_upsert_record_category {
    "category_id": "doc_tecnico",
    "category": {
      "name": "Technical Doc",
      "metadata": [
        { "key": "language", "order": 0 },
        { "key": "area", "required": true, "order": 1 },
        { "key": "origin", "required": true, "order": 2 },
        { "key": "doc_number", "order": 3,
          "computed_from": [
            { "key": "language", "use": "code" },
            { "key": "area", "use": "code" }
          ],
          "sequence_digits": 3 }
      ],
      "slug_separator": "-",
      "slug_from": [
        { "key": "language", "use": "code" },
        { "key": "area", "use": "code" },
        { "key": "origin", "use": "label" },
        { "key": "doc_number", "use": "label" }
      ]
    }
  }

// 4. Check what fields are needed
→ sutram_get_record_category_detail { "category_id": "doc_tecnico" }

// 5. Create a record — slug is auto-generated from slug_from
→ sutram_create_record { "category_id": "doc_tecnico",
    "metadata": { "language": "PT", "area": "Automação", "origin": "SWA" } }
← { "record": { "id": "...", "name": "PT-0100-SWA-001", "slug": "PT-0100-SWA-001",
    "metadata": { "language": "PT", "area": "Automação", "origin": "SWA",
                   "doc_number": "001", "slug": "PT-0100-SWA-001" } } }

// 6. Create another record with same number base → sequence increments
→ sutram_create_record { "category_id": "doc_tecnico",
    "metadata": { "language": "PT", "area": "Automação", "origin": "PPC" } }
← { "record": { "name": "PT-0100-PPC-002", "slug": "PT-0100-PPC-002", ... } }

Note how:

• The number base PT-0100 (from computed_from: language + area) determines sequential uniqueness
• The slug PT-0100-SWA-001 (from slug_from) includes origin + the sequence number
• The second record receives sequence 002 because it shares the same number base PT-0100

---

Wiki and Knowledge Graph

Sutram's Wiki is a knowledge graph layer over the project. Beyond files and records, you create wiki nodes (entities, concepts, or synthesis pages) and connect them with [[slug]] mentions, forming a navigable network of backlinks and typed relations. It is the structured memory that lets an AI answer questions grounded in the project's own sources.

Concepts

• Wiki node (WikiNode) — An abstract referenceable entity (a concept, theme, or synthesis page) that [[slug]] mentions point to. It is neither a folder nor a file: it has a slug, an optional category, metadata, and an optional markdown body.
• [[slug]] mention — An inline reference, within a node's markdown, to another item by its slug. A mention whose target does not yet exist stays pending until it is created.
• Backlink — The inverse of a mention: all the items pointing to a target (the "Mentioned in (N)" panel).
• Typed relation — A mention with a label (e.g., revokes, amends, regulates) that gives semantics to the graph edge.
• Synthesis vs. full text — The content_markdown is the node's curated synthesis; the source_text is the full text of the mirrored document, indexed by full-text search (sutram_search_wiki).

Answer flow

The wiki usage pattern for answering a question:

1. Search      →  sutram_search_wiki(question)        // full-text over the content
2. Read        →  sutram_get_wiki_node(slug | id)     // synthesis + full text
3. Navigate    →  sutram_get_backlinks / sutram_get_outgoing_mentions
4. Synthesize the answer, grounded in the sources found

Wiki Tools

Tool	Description
sutram_create_wiki_node	Creates a wiki node (fuzzy-matches the name to avoid duplicates)
sutram_update_wiki_node	Updates a node's name, category, metadata, body, or typed relations
sutram_get_wiki_node	Returns a node by id or slug, with synthesis and full text
sutram_delete_wiki_node	Soft-deletes a node (mentions revert to pending) — confirm first
sutram_search_wiki	Full-text search over name + synthesis + full text (from a question)
sutram_search_wiki_nodes	Lists/filters nodes by name substring or by category
sutram_sync_wiki_source	Populates a mirror node's source_text from the record's file
sutram_set_wiki_relation_labels	Sets the project's relation vocabulary (passive→active labels)
sutram_get_outgoing_mentions	Lists the [[slug]] mentions leaving a source (resolved/pending)
sutram_get_backlinks	Lists an item's backlinks (who mentions it)
sutram_resolve_slug	Resolves a mention slug to the item it points to (discovery)

Wiki read operations are available to project members; write operations follow the editing roles (see Permissions).

sutram_create_wiki_node

Creates a WikiNode — a referenceable entity (concept, theme, or synthesis page) that [[slug]] mentions point to. Before creating, it fuzzy-matches the name against the project catalog: if a close-enough node already exists, it is returned (status matched) instead of creating a duplicate.

Parameters:

Parameter	Type	Required	Description
name	string	Yes	Display name (e.g., "i18n folder structure")
slug	string	No	Explicit slug (generated from the name if omitted)
category	string	No	Node-type category id
content_markdown	string	No	Markdown body (the curated synthesis). Omit for a stub node.
source_text	string	No	Full text of the mirrored document, indexed by search
metadata	object	No	Free-form attributes
created_autonomously	boolean	No	Marks the node as AI-created (default false)

sutram_update_wiki_node

Updates a node's name, category, metadata, or body. The slug is stable and is not regenerated on rename. The mentions parameter defines typed outgoing edges that override the [[ ]] mentions extracted from the body.

Parameters:

Parameter	Type	Required	Description
id	string	Yes	Node UUID
name	string	No	New display name
category	string	No	New category id
content_markdown	string	No	New markdown body
source_text	string	No	New full text
metadata	object	No	Metadata map (replaces the previous one)
mentions	array	No	Typed edges: [{slug, label}] (e.g., label: "revokes")

sutram_get_wiki_node

Returns a node by id or slug (provide exactly one), including category, metadata, curated synthesis, and — for nodes that mirror a record — the document's full text, inline in the markdown ("📄 Full text" section).

Parameters:

Parameter	Type	Required	Description
id	string	Yes*	Node UUID
slug	string	Yes*	Node slug

*Provide id or slug.

sutram_delete_wiki_node

Destructive. Soft-deletes a node; mentions that pointed to it revert to pending. Confirm with the user before calling.

Parameters:

Parameter	Type	Required	Description
id	string	Yes	Node UUID

sutram_search_wiki

Full-text search over the wiki content — the way to find material from a question when you don't know slugs or ids. Ranks nodes by how well their name, synthesis, and full text match the query (Portuguese stemming) and returns a highlighted snippet per result.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Free-form query. Supports quoted phrases, exclusion with -, and or.
limit	integer	No	Maximum results (default 10, max 50)

sutram_search_wiki_nodes

Lists the project's nodes, optionally filtered by name substring (query) or by category. Use it to browse the entity/concept catalog or find a node before linking to it.

Parameters:

Parameter	Type	Required	Description
query	string	No	Filter by name substring
category	string	No	Filter by category id
limit	integer	No	Maximum results (default 50)

sutram_sync_wiki_source

Populates a mirror node's source_text (the full-text search substrate) from the markdown extracted from the linked record (default texto_full.md), read from storage. Use after sutram_create_wiki_node when the document body is too large to pass inline. Idempotent.

Parameters:

Parameter	Type	Required	Description
id	string	Yes*	Node UUID
slug	string	Yes*	Node slug
record_folder_id	string	No	UUID of the source record (default: the node's metadata.record_folder_id)
filename	string	No	File name in the record (default texto_full.md)

*Provide id or slug.

sutram_set_wiki_relation_labels

Sets the project's relation vocabulary: a map of passive→active labels (e.g., {"regulamentado_por": "regulamenta", "revogado_por": "revoga"}). The graph collapses inverse edges to the active voice; the node page renders backlinks in the passive voice. Call once per project after defining typed mentions. Merges with the existing map.

Parameters:

Parameter	Type	Required	Description
labels	object	Yes	Map of passive label → active label

sutram_get_outgoing_mentions

Returns the outgoing mentions of a source — the [[slug]] it points to, each marked as resolved or pending. Identify the source by slug or by id + kind.

Parameters:

Parameter	Type	Required	Description
slug	string	Yes*	Source slug
id	string	Yes*	Source UUID (with kind)
kind	string	No	Source type: wiki_node | content_item

*Provide slug or id + kind.

sutram_get_backlinks

Returns an item's backlinks — the sources whose markdown mentions it via [[slug]] (the "Mentioned in (N)" panel). Identify the target by slug (resolved automatically) or by id + kind.

Parameters:

Parameter	Type	Required	Description
slug	string	Yes*	Target slug
id	string	Yes*	Target UUID (with kind)
kind	string	No	Target type: wiki_node | content_item | folder

*Provide slug or id + kind.

sutram_resolve_slug

Resolves a slug (the token inside a [[slug]] mention) to the item it points to in the project, returning its type (content_item or folder), id, and name. An unresolved slug indicates a pending mention — the target does not yet exist.

Parameters:

Parameter	Type	Required	Description
slug	string	Yes	Slug to resolve (e.g., "estrutura-de-pastas-i18n")

Example: Wiki Flow

// 1. Find material from a question
→ sutram_search_wiki { "query": "multilingual folder structure" }

// 2. Read the most relevant node in full (synthesis + full text)
→ sutram_get_wiki_node { "slug": "estrutura-de-pastas-i18n" }

// 3. See everywhere it is referenced
→ sutram_get_backlinks { "slug": "estrutura-de-pastas-i18n" }

// 4. Audit the outgoing mentions (which resolve, which are pending)
→ sutram_get_outgoing_mentions { "slug": "estrutura-de-pastas-i18n" }

---

Document Classes and Governance

Document Classes are Sutram's formal governance layer: they turn a plain record category into a governed workflow, with lifecycle states, per-state roles, need-to-know visibility, and an audit trail of every transition. It is the mechanism for documents that require formal approval (submit → review → approve) and stage-based confidentiality.

Plan requirement: Document Classes are a Max plan feature.

Concepts

• Document Class — A record category "graduated" into a governed workflow. It defines states, roles, per-state permissions (state_access), and transitions.
• Governed document — A record that belongs to a Class; it exists as a family with one or more versions, each in a lifecycle state.
• Lifecycle — A set of states (one initial, optionally terminal), roles, actions (transitions from → to with allowed roles), and state_access (read/write per role in each state).
• Need-to-know — Each state reveals the document only to the roles with read access in that state; a (state, role) pair missing from state_access means no access.
• Version axis — Versioned Classes have an axis (e.g., rev: A, B, C); new revisions are born in an entry state.
• Grant — A (user, class role) pair. A user can hold multiple grants in the same Class (e.g., a scoped Author plus an unscoped Viewer); their effects combine (access = the best among matching grants).
• Metadata scope — An optional restriction on a grant: the role applies only where the document's metadata matches the scope; outside it, it is as if the user had no role (need-to-know — the document is not even visible). A scope is an OR of groups, each group an AND of conditions over enum/boolean metadata; enum values are the labels, and the special value "" matches "no value" (key absent/empty).

Governance Tools

Tool	Description
sutram_list_document_classes	Lists the accessible Document Classes (with stats for owner/admin)
sutram_list_governed_documents	Lists a Class's documents (respects need-to-know; filters by state/tag)
sutram_graduate_document_class	Graduates a record category into a governed Class (author→reviewer→approver preset)
sutram_set_document_class_lifecycle	Sets a Class's full lifecycle (read-modify-write)
sutram_revert_document_class	Reverts a Class to a plain category (blocked if documents still exist)
sutram_create_document	Creates a governed document (family + 1st version) in an entry state
sutram_create_documents	Batch-creates several documents of the same Class (supports dry_run)
sutram_create_document_version	Creates a new revision of a governed document
sutram_transition_document	Triggers a transition (submit/approve/reject) on a version
sutram_list_class_grants	Lists the grants (user → class role, with scope) of a Class
sutram_grant_class_role	Grants a class role to an active member (by email), optionally scoped
sutram_revoke_class_role	Revokes one grant (user + role) in a Class

Who can read, write, and trigger each transition is determined by the role × state matrix defined in the Class itself. Graduating/reverting classes, editing the lifecycle, and administering grants are owner and admin operations (manage_record_categories), on the Max plan.

sutram_list_document_classes

Lists the Document Classes you have access to. Owner/admin see all governed classes (with volume stats); member/viewer see only the classes where they hold a role. Each item carries uid, category_id, name, your role, and doc_count. It is the entry point before sutram_list_governed_documents.

Parameters: None

sutram_list_governed_documents

Lists the governed documents of a Class (by its uid). Respects need-to-know: it returns only documents in states you can read. Supports filtering by state, tag conditions, version mode, and pagination.

Parameters:

Parameter	Type	Required	Description
category_uid	string	Yes	Immutable UUID of the Class (from sutram_list_document_classes)
states	array	No	State ids to include (intersected with those you can read)
tag_conditions	array	No	{key, value} filters (AND) over the version's metadata
all_versions	boolean	No	false (default) = one row per family; true = one per version
page	integer	No	Page (default 1)
per_page	integer	No	Page size (default 50, max 200)

sutram_graduate_document_class

Graduates a plain record category into a governed Document Class (Max plan), applying the default preset (author → reviewer → approver), fully editable afterward with sutram_set_document_class_lifecycle.

Parameters:

Parameter	Type	Required	Description
category_id	string	Yes	Id of the record category to graduate

sutram_set_document_class_lifecycle

Replaces the entire lifecycle of a Class — the single tool for governance: states, roles, per-state permissions (state_access), transitions (actions), version axis, and display. Read-modify-write: call sutram_get_record_category_detail first (it returns the category with the lifecycle), change what you need, and resend the whole object.

Parameters:

Parameter	Type	Required	Description
category_id	string	Yes	Document Class id
lifecycle	object	Yes	Full lifecycle object (replaces the existing one)

lifecycle structure:

• states: [{id, label, color, order, initial?, terminal?}] — exactly one initial.
• roles: [{id, label}]
• actions: [{id, label, from:[state], to, allowed_roles:[role], requires_note?}] — from:["*"] = any state.
• state_access: {state: {role: "read" | "write"}} — a missing pair = no access.

sutram_revert_document_class

Reverts a Document Class to a plain record category, removing governance (lifecycle + role↔user assignments). Blocked while the Class still has governed documents — delete them first. It does not erase content; it only removes the governance layer from an empty class.

Parameters:

Parameter	Type	Required	Description
category_id	string	Yes	Id of the Class to revert

sutram_create_document

Creates a governed document (family + first version), in an entry state, with a computed identity (slug). Use it for the first version of a versioned class and for every document of a non-versioned class. Call sutram_get_record_category_detail beforehand to learn the required fields and the version axis.

Parameters:

Parameter	Type	Required	Description
category_id	string	Yes	Document Class id
metadata	object	Yes	Typed metadata that forms the document/slug
version_values	object	No	Version-axis values (e.g., {"rev": "A"}) — required if the class has an axis
lifecycle_state	string	No	Entry state (default: the class's initial state)
name	string	No	Custom name (default: computed slug)

sutram_create_documents

Batch-creates several governed documents of the same Class in a single call (bootstrap / master register). Each entry is the first version of a family; the slug sequence advances correctly. Recommended: call with dry_run: true to preview, then dry_run: false to apply. Idempotent by slug in classes with deterministic slugs.

Parameters:

Parameter	Type	Required	Description
category_id	string	Yes	Class id (shared by all entries)
documents	array	Yes	Documents to create (max 200), each {metadata, version_values?, lifecycle_state?, name?}
dry_run	boolean	No	Preview only — resolves identities without persisting (default false)

sutram_create_document_version

Creates a new revision of a governed document from the current version: a floating sibling with a new revision, in an entry state, inheriting the identity (slug). Use it to issue a new revision (e.g., revision B of an approved drawing). The class must have a version axis and the current state must allow versioning.

Parameters:

Parameter	Type	Required	Description
document_id	string	Yes	UUID of the governed document family
version_values	object	No	Version-axis values (e.g., {"rev": "B"}) — required if there is an axis
copy_forward	boolean	No	Copies the current version's files to the new one (default true)

sutram_transition_document

Triggers a lifecycle transition on a governed document version (e.g., submit, approve, reject). Respects the "who-can-trigger" matrix (role × state); some transitions require a note. Records the change in the audit trail.

Parameters:

Parameter	Type	Required	Description
version_id	string	Yes	Id of the version to transition (from sutram_list_governed_documents)
action	string	Yes	Id of the lifecycle action to trigger (defined in the class)
note	string	No	Justification — required by transitions that demand a note

Class-role grants (new in v1.62)

Who holds which role in a Class is stored as grants — one row per (user, role), each with an optional metadata scope. A user accumulates grants in the same Class and their effects combine. Three granular tools administer grants (deliberately not replace-all: replacing the whole set would revoke people's access by omission). All three are owner/admin operations; granting and revoking also require the Max plan. Granting and revoking change who can see and act on governed documents — an assistant should only call them under an explicit user instruction naming the person and the role. Project membership (inviting users) remains a web-UI operation; granting a class role to an existing active member is the boundary.

Every grant, revocation, and scope change is recorded in the audit trail (document_class.role_granted / role_revoked / role_scope_changed).

sutram_list_class_grants

Lists the grants of a Document Class: member email and name, role (id + label), scope, who granted it, and when.

Parameters:

Parameter	Type	Required	Description
category_uid	string	Yes	Immutable UUID of the Class (from sutram_list_document_classes); the textual category_id is accepted as an alias

sutram_grant_class_role

Grants a class role to an active project member (by email), optionally restricted by a metadata scope. Idempotent: re-granting an existing (user, role) pair only updates its scope — and only when scope is explicitly passed (omitted = the existing scope is preserved; explicit null = clears it, the role becomes class-wide). The scope is validated against the category's metadata definitions before anything is written.

Parameters:

Parameter	Type	Required	Description
category_uid	string	Yes	Immutable UUID of the Class (category_id accepted as alias)
user_email	string	Yes	Email of an active project member
role_id	string	Yes	Class role id (from the lifecycle's roles[])
scope	object | null	No	Metadata scope: {"groups": [[{"key": "...", "values": ["..."]}]]} — OR of groups, each an AND of conditions over enum/boolean metadata; "" matches "no value"

sutram_revoke_class_role

Revokes one grant (user + class role) in a Document Class. The user keeps any other roles they hold in the Class.

Parameters:

Parameter	Type	Required	Description
category_uid	string	Yes	Immutable UUID of the Class (category_id accepted as alias)
user_email	string	Yes	Email of the grant holder
role_id	string	Yes	Class role id to revoke

Example: Scoped Grant

// Ana reviews only Civil Engineering documents; everything else stays invisible to her
→ sutram_grant_class_role {
    "category_uid": "cls-1",
    "user_email": "ana@example.com",
    "role_id": "reviewer",
    "scope": { "groups": [[ { "key": "discipline", "values": ["Civil Engineering"] } ]] }
  }

// Audit who holds what
→ sutram_list_class_grants { "category_uid": "cls-1" }

Example: Governance Flow

// 1. List the governed Document Classes
→ sutram_list_document_classes

// 2. List a Class's documents, filtering by state
→ sutram_list_governed_documents { "category_uid": "cls-1", "states": ["em_revisao"] }

// 3. Approve a version, with justification
→ sutram_transition_document {
    "version_id": "ver-9",
    "action": "aprovar",
    "note": "Per technical review."
  }

---

Document Comments

AI assistants can list, create, reply to, resolve, and delete comments on project files. Comments created via MCP appear in real time in the web interface and vice versa, thanks to PubSub broadcasting.

Position-type restriction: Via MCP, the AI can create only file_level (whole-file) or markdown (text-anchored, in markdown files) comments. Position types that require GUI coordinates (pdf_page, aps_3d, aps_2d, image) can be read but not created via MCP.

Comment Tools

Tool	Description	Permission
sutram_list_comments	Lists all top-level comments on a content item	Any participant
sutram_get_comment_thread	Gets a comment with its full reply thread	Any participant
sutram_create_comment	Creates a file-level or markdown comment	Any participant
sutram_reply_to_comment	Replies to a top-level comment	Any participant
sutram_resolve_comment	Resolves or reopens a comment thread	Any participant
sutram_delete_comment	Deletes a comment and all its replies	Author, Owner, or Admin

sutram_list_comments

Lists all top-level comments on a content item. Returns the comment content, author, position type, resolution status, and reply count.

Parameters:

Parameter	Type	Required	Description
content_item_id	string	Yes	UUID of the content item
include_resolved	boolean	No	Whether to include resolved comments (default: true)

Example:

{
  "content_item_id": "abc-123"
}

Response:

{
  "comments": [
    {
      "id": "comment-1",
      "content": "This section needs review",
      "position_type": "file_level",
      "resolved": false,
      "replies_count": 2,
      "user": { "id": "...", "name": "Alice", "email": "alice@example.com" },
      "created_at": "2026-03-10T14:30:00Z"
    }
  ],
  "total": 1
}

---

sutram_get_comment_thread

Gets a single comment with its full reply thread, resolution status, and author details.

Parameters:

Parameter	Type	Required	Description
comment_id	string	Yes	Comment UUID

Response:

{
  "comment": {
    "id": "comment-1",
    "content": "This section needs review",
    "position_type": "file_level",
    "resolved": false,
    "resolved_at": null,
    "resolved_by": null,
    "replies_count": 1,
    "user": { "id": "...", "name": "Alice", "email": "alice@example.com" },
    "created_at": "2026-03-10T14:30:00Z",
    "replies": [
      {
        "id": "reply-1",
        "content": "I'll take care of it",
        "user": { "id": "...", "name": "Bob", "email": "bob@example.com" },
        "created_at": "2026-03-10T15:00:00Z"
      }
    ]
  }
}

---

sutram_create_comment

Creates a comment on a content item. The AI can create file_level (default) or markdown comments.

Parameters:

Parameter	Type	Required	Description
content_item_id	string	Yes	UUID of the content item
content	string	Yes	Comment text
position_type	string	No	"file_level" (default) or "markdown"
text_anchor	object	No	For markdown: {exact_text, prefix, suffix}
original_text_snippet	string	No	For markdown: the selected text snippet

Example — file-level comment:

{
  "content_item_id": "abc-123",
  "content": "This file needs to be updated with the latest specifications."
}

Example — text-anchored markdown comment:

{
  "content_item_id": "abc-123",
  "content": "Typo: should be 'specification' not 'specificaiton'",
  "position_type": "markdown",
  "text_anchor": {
    "exact_text": "specificaiton",
    "prefix": "the latest ",
    "suffix": " document"
  },
  "original_text_snippet": "specificaiton"
}

---

sutram_reply_to_comment

Replies to an existing top-level comment. Replies cannot be nested (no reply-to-reply).

Parameters:

Parameter	Type	Required	Description
comment_id	string	Yes	UUID of the top-level comment
content	string	Yes	Reply text

Example:

{
  "comment_id": "comment-1",
  "content": "Good catch, I've fixed the typo."
}

---

sutram_resolve_comment

Resolves or reopens a comment thread. Resolved comments indicate that the issue has been handled.

Parameters:

Parameter	Type	Required	Description
comment_id	string	Yes	Comment UUID
action	string	Yes	"resolve" or "reopen"

Example:

{
  "comment_id": "comment-1",
  "action": "resolve"
}

---

sutram_delete_comment

Deletes a comment and all its replies. Only the comment's author or the project owner/admin can delete.

Parameters:

Parameter	Type	Required	Description
comment_id	string	Yes	Comment UUID

---

Example: Complete Comments Flow

// 1. List comments on a file
→ sutram_list_comments { "content_item_id": "abc-123" }
← { "comments": [...], "total": 3 }

// 2. Read a specific comment thread
→ sutram_get_comment_thread { "comment_id": "comment-1" }
← { "comment": { "content": "Needs review", "replies": [...] } }

// 3. Create a new comment
→ sutram_create_comment {
    "content_item_id": "abc-123",
    "content": "Section 3.2 references an outdated standard."
  }
← { "comment": { "id": "comment-4", "content": "Section 3.2 references...", ... } }

// 4. Reply to it
→ sutram_reply_to_comment {
    "comment_id": "comment-4",
    "content": "Updated to reference ISO 9001:2025."
  }
← { "reply": { "id": "reply-1", "content": "Updated to reference...", ... } }

// 5. Resolve the comment
→ sutram_resolve_comment { "comment_id": "comment-4", "action": "resolve" }
← { "comment": { "id": "comment-4", "resolved": true, ... } }

All comment changes are broadcast in real time to users viewing the same document in the web interface.

---

Project Chat

The project chat is a human-to-human, project-scoped message feed — distinct from comments, which are anchored to a document. Via MCP, the AI can read the history, check for unread messages, and post messages.

Warning — messages are outward-facing: sutram_send_chat_message and sutram_reply_to_chat_message are visible to other members in real time and trigger a push notification. Confirm with the user before posting on their behalf.

Chat Tools

Tool	Description
sutram_list_chat_messages	Lists the chat messages (oldest→newest; search and pagination)
sutram_get_chat_thread	Gets a message with its reply thread (one level)
sutram_send_chat_message	Posts a new message (text and/or an attachment from a project item)
sutram_reply_to_chat_message	Replies to a top-level message
sutram_get_chat_unread_count	Returns how many messages from other members have not yet been read
sutram_mark_chat_visited	Marks the chat as read (resets the unread counter)

sutram_list_chat_messages

Lists the project chat messages, from oldest to newest, excluding deleted ones. Supports pagination (before_id) and text search (content or author).

Parameters:

Parameter	Type	Required	Description
limit	integer	No	Maximum messages (default 20, max 100)
before_id	string	No	Returns messages before this one (pagination cursor)
search	string	No	Filter by text in the content or in the author's name/email

sutram_get_chat_thread

Gets a message with its reply thread (one level). If the given message is a reply, it returns the parent's thread.

Parameters:

Parameter	Type	Required	Description
message_id	string	Yes	UUID of any message in the thread

sutram_send_chat_message

Outward-facing. Posts a new message to the project chat as the authenticated user; other members see it in real time and receive a push notification. Provide content (text) and/or attach a project file/link via content_item_id.

Parameters:

Parameter	Type	Required	Description
content	string	Yes*	Message text (max 5000 characters)
content_item_id	string	No	UUID of a project file/link to attach

*content is required unless content_item_id is provided.

sutram_reply_to_chat_message

Outward-facing. Replies to a top-level message (one-level threading); the original author and other members are notified. You cannot reply to your own message, to a reply, or to a deleted message.

Parameters:

Parameter	Type	Required	Description
message_id	string	Yes	UUID of the top-level message being replied to
content	string	Yes*	Reply text (max 5000 characters)
content_item_id	string	No	UUID of a project file/link to attach

*content is required unless content_item_id is provided.

sutram_get_chat_unread_count

Returns how many messages from other members the current user has not yet seen (since the last visit, or all of them if never visited). Read-only.

Parameters: None

sutram_mark_chat_visited

Marks the project chat as read for the current user, resetting the unread counter. It posts nothing — it only records the visit.

Parameters: None

Example: Chat Flow

// 1. Check how many new messages there are
→ sutram_get_chat_unread_count

// 2. Read the recent messages
→ sutram_list_chat_messages { "limit": 20 }

// 3. Post an update (outward-facing — confirm first)
→ sutram_send_chat_message { "content": "MCP guide updated: Wiki, Governance, and Chat." }

// 4. Mark the chat as read
→ sutram_mark_chat_visited

---

Limitations

The following operations are not yet available via MCP and must be performed through the Sutram web interface. They will be added in future versions:

• Sharing: Share links cannot be generated
• Positioned comments: Creating comments anchored to PDF pages, CAD coordinates, or image positions requires the web interface

---

Permissions

Your MCP access respects the same permissions as the web interface:

Role	Browse	Upload/Create	Move	Delete	Versioning	Record Schema	Records	Comments
Owner	Yes	Yes	Yes	Yes	Full (publish, force-release)	Full (CRUD of definitions and categories)	CRUD	Full (list, create, reply, resolve, delete any)
Admin	Yes	Yes	Yes	Yes	Full (publish, create new version, force-release)	Full (CRUD of definitions and categories)	CRUD	Full (list, create, reply, resolve, delete any)
Member	Yes	Yes	Yes	Yes	Enable/disable, check-out/check-in, publish, create new version	Read-only	CRUD	List, create, reply, resolve, delete own
Viewer	Yes	No	No	No	Read-only (list/download)	Read-only	Read-only	Yes (participation)

Viewers connect with a read-only surface: they can browse, search, and download content and participate in comments and chat; the content-write tools (upload, create, move, delete, version, edit records/wiki/governance) are hidden and denied.

Additional families:

• Wiki — Read (get_wiki_node, search_wiki, get_backlinks, get_outgoing_mentions, resolve_slug) is available to any participant, including viewers; write (create_wiki_node, update_wiki_node, delete_wiki_node, sync_wiki_source, set_wiki_relation_labels) follows the editing roles.
• Chat — Reading and posting are available to all project participants, including viewers (chat is a participation tool). Posting and replying are outward-facing actions (they notify the team).
• Governance (Document Classes) — A Max plan feature. Graduating/reverting classes, editing the lifecycle, and administering class-role grants (list_class_grants, grant_class_role, revoke_class_role) are owner and admin operations; reading documents and triggering transitions follow the role × state matrix defined in each Class (need-to-know visibility), further narrowed by each grant's metadata scope when one is set.

---

Supported File Types

Sutram automatically detects MIME types from file extensions. Common supported formats:

Category	Extensions
Images	.jpg, .jpeg, .png, .gif, .webp, .svg
Documents	.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx
Text	.txt, .csv, .json, .xml, .md
Media	.mp4, .mp3, .wav
Archives	.zip
CAD	.dwg, .dxf, .rvt, .ifc

Files with unrecognized extensions are uploaded as application/octet-stream.

---

Supported Link Platforms

Video platforms

YouTube, Vimeo, DailyMotion, Wistia, Loom, and TikTok. The platform is detected automatically from the URL, and thumbnails are extracted when available.

Audio platforms

Spotify, SoundCloud, Apple Podcasts, Anchor, and others. The platform is detected automatically from the URL.

Web links

Any valid HTTP/HTTPS URL. The page title, description, and favicon are fetched automatically.

---

Examples

Migrate medical exams from hospital portals

"Download my ultrasound exam from the hospital portal and organize it in Sutram in the requesting doctor's folder."

The AI assistant will:

1. Access the hospital portal (via browser)
2. Download the PDF report and the image files
3. Use sutram_create_folder to build the folder structure in one call: Doctor Name / Exam Type / YYYY-MM-DD
4. Use sutram_request_upload + sutram_confirm_upload to upload each file directly to S3
5. Clean up the local temporary files

This workflow ensures that medical data is properly organized and that no sensitive file remains on the local computer.

Upload a local file

"Upload the file report.pdf from my desktop to the 'Reports' folder in Sutram."

Claude will read the file, use sutram_get_folder to find the "Reports" folder, then sutram_request_upload to obtain a presigned URL, upload the file directly to S3 via HTTP PUT, and call sutram_confirm_upload to finalize.

Organize project content

"Create a folder structure for our construction project: Plans, Reports, and Photos. Then upload these site photos."

Claude will use sutram_create_folder for each top-level folder, then sutram_request_upload + sutram_confirm_upload to upload each photo into the correct folder.

Clean up old files

"Delete all files in the 'Temp' folder."

Claude will use sutram_get_folder to list the folder contents, then sutram_delete for each file.

Reorganize folder structure

"Move all the contents of the '2024' folder to '2024-Archive' to free up space in the main view."

Claude will use sutram_move_contents to transfer all subfolders and files from the source to the target folder in a single operation. If any item has a conflicting name, it is automatically renamed with numeric suffixes.

Move a specific file

"Move the file 'contract.pdf' to the 'Legal' folder."

Claude will use sutram_get_folder to find the file and the target folder, then sutram_move_item to move the file. If a file with the same name already exists in the target folder, it is automatically renamed (e.g., contract (1).pdf).

Save a web link

"Save this article to my project: https://example.com/building-codes-2026"

Claude will use sutram_create_web_link with the URL. Sutram automatically fetches the page title and favicon, so the link appears with its correct name in the project.

Organize video references

"Add these YouTube videos to the 'Training' folder: [video1 URL], [video2 URL]."

Claude will use sutram_get_folder to find the "Training" folder, then call sutram_create_video_link for each URL. Sutram detects that they are YouTube videos and extracts thumbnails automatically.

Download a file

"Give me the download link for the file 'site-plan.pdf'."

Claude will use sutram_get_folder to find the file, then sutram_get_item to obtain a presigned download URL. The URL is temporary and can be used to download the file directly.

Tag and search folders

"Organize my medical exams by patient and exam type, then find all of patient João's folders."

Claude will:

1. Use sutram_create_folder with path and tags to create structured folders with metadata
2. Use sutram_set_folder_tags to add or update tags on existing folders
3. Use sutram_search_folders with tag_name: "patient" and tag_value: "João" to find all matching folders (substring matching — it also finds "João Pedro", "João Silva")

Tags let AI assistants create rich, searchable organizational structures without relying on folder names alone.

Discover tags and run AND searches

"Find all of patient João's USG exams inside Dr. Mion's folder."

Claude will:

1. Use sutram_get_tag_keys with the folder ID to discover the tag keys available in that scope
2. Use sutram_search_folders with multiple AND conditions:

   {
     "conditions": [
       { "key": "patient", "value": "João" },
       { "key": "exam_type", "value": "USG" }
     ],
     "folder_id": "dr-mion-folder-id"
   }
   

3. Return only folders that match both conditions within the specified hierarchy

---

Uploading Files via Script

When uploading files through an AI assistant, the assistant uses the two-step presigned-URL flow: sutram_request_upload to obtain a presigned S3 PUT URL, then it uploads the file directly to S3 and finally calls sutram_confirm_upload to create the file record. This approach avoids the overhead of base64 encoding and has no practical file-size limit beyond your plan's storage quota.

For automation or batch uploads outside the AI assistant's context, you can call the MCP endpoint directly over HTTP.

Note: the example below uses the legacy /mcp endpoint with the x-project-key/x-user-key headers — kept for direct scripts. To connect an MCP client (Claude, Cursor, etc.), use the recommended method described in Connecting Sutram to Claude (OAuth connector or /mcp/v2 bridge).

How the MCP HTTP endpoint works

Sutram's MCP server uses the Streamable HTTP transport (JSON-RPC 2.0 over HTTPS):

1. Initialize a session — POST https://app.sutram.io/mcp with the initialize method
2. Capture the session ID — from the mcp-session-id response header
3. Send a notification — notifications/initialized (required by the MCP protocol)
4. Call tools — POST with the tools/call method, passing the tool name and arguments

All requests must include the authentication headers (x-project-key and x-user-key) and, after initialization, the mcp-session-id header.

Example: Node.js upload script

import { readFileSync, statSync } from "node:fs";
import { basename, extname } from "node:path";
import { lookup } from "mime-types";

const ENDPOINT = "https://app.sutram.io/mcp";
const HEADERS = {
  "x-project-key": "sk_proj_YOUR_PROJECT_KEY",
  "x-user-key": "sk_user_YOUR_USER_KEY",
};

let sessionId = null;
let requestId = 0;

async function mcpRequest(method, params = {}) {
  const headers = {
    "Content-Type": "application/json",
    Accept: "application/json, text/event-stream",
    ...HEADERS,
  };
  if (sessionId) headers["mcp-session-id"] = sessionId;

  const response = await fetch(ENDPOINT, {
    method: "POST",
    headers,
    body: JSON.stringify({ jsonrpc: "2.0", method, params, id: ++requestId }),
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);

  const sid = response.headers.get("mcp-session-id");
  if (sid) sessionId = sid;

  const contentType = response.headers.get("content-type") || "";
  if (contentType.includes("text/event-stream")) {
    // Parse SSE: find the last "data:" line with a JSON-RPC response
    const text = await response.text();
    const events = text.split("\n\n").filter(Boolean);
    for (const event of events.reverse()) {
      const dataLine = event.split("\n").find((l) => l.startsWith("data: "));
      if (dataLine) return JSON.parse(dataLine.slice(6));
    }
  }
  return response.json();
}

async function mcpNotify(method, params = {}) {
  const headers = { "Content-Type": "application/json", ...HEADERS };
  if (sessionId) headers["mcp-session-id"] = sessionId;
  await fetch(ENDPOINT, {
    method: "POST",
    headers,
    body: JSON.stringify({ jsonrpc: "2.0", method, params }),
  });
}

// ── Usage ──

async function main() {
  // 1. Initialize MCP session
  await mcpRequest("initialize", {
    protocolVersion: "2024-11-05",
    capabilities: {},
    clientInfo: { name: "my-upload-script", version: "1.0.0" },
  });
  await mcpNotify("notifications/initialized");

  // 2. Request a presigned upload URL
  const filePath = process.argv[2];
  const folderId = process.argv[3] || null;
  const filename = basename(filePath);
  const fileSize = statSync(filePath).size;
  const contentType = lookup(extname(filePath)) || "application/octet-stream";

  const reqResult = await mcpRequest("tools/call", {
    name: "sutram_request_upload",
    arguments: { filename, file_size: fileSize, content_type: contentType, folder_id: folderId },
  });

  const { upload_url, s3_key, file_id } = JSON.parse(reqResult.result.content[0].text);

  // 3. Upload file directly to S3
  const fileContent = readFileSync(filePath);
  const putResponse = await fetch(upload_url, {
    method: "PUT",
    headers: { "Content-Type": contentType },
    body: fileContent,
  });

  if (!putResponse.ok) throw new Error(`S3 upload failed: ${putResponse.status}`);

  // 4. Confirm the upload
  const confirmResult = await mcpRequest("tools/call", {
    name: "sutram_confirm_upload",
    arguments: { file_id, s3_key, filename, content_type: contentType, file_size: fileSize, folder_id: folderId },
  });

  console.log(JSON.stringify(confirmResult, null, 2));
}

main();

Save it as upload.mjs and run:

node upload.mjs /path/to/report.pdf "target-folder-uuid"

Integration with a Claude Code skill

If you use Claude Code, you can wrap this script as a skill so the assistant can invoke it automatically when it needs to upload files. Place the script at .claude/skills/sutram-upload/scripts/upload.mjs and create a SKILL.md that instructs Claude on how to call it. That way, when the assistant encounters a file to upload, it delegates the heavy I/O to the external script while keeping the orchestration in the conversation.

Key points

• No file-size limit beyond your Sutram plan's storage quota
• Files are uploaded directly to S3 via a presigned URL — no base64 encoding, no data passing through the web server
• The script handles the full MCP handshake (initialize -> notify -> tool call)
• The response can come as JSON or Server-Sent Events (SSE) depending on processing time — the script handles both
• Credentials can be read from .mcp.json to avoid hardcoding

---

REST API

In addition to the MCP tools, Sutram provides a REST API for read-only consumption of the project's content. It uses the same dual-key authentication and is ideal for external applications, dashboards, and scripts.

Base URL: https://sutram.io/api/v1

Endpoints:

Endpoint	Description
GET /api/v1/project	Project information
GET /api/v1/folders	Lists root folders
GET /api/v1/folders/:id	Folder details with subfolders and items
GET /api/v1/content	Lists content items with filtering, tag search, and pagination
GET /api/v1/content/:id	Content-item details with presigned download URLs

Full documentation: Sutram REST API v1 Reference