Guía del Sutram MCP Server

Version: 0.111.0 Date: 2026-03-14 Status: In development

Descripcion general

Sutram Acceso Remoto permite que asistentes de IA y herramientas de automatizacion se conecten a tus proyectos a traves del Model Context Protocol (MCP). Una vez configurado, tu asistente de IA puede explorar carpetas, subir archivos, agregar enlaces web/video/audio, gestionar contenido e interactuar con comentarios de documentos en tus proyectos de Sutram — todo con autenticacion y permisos adecuados.

Como funciona

AI Assistant (Claude, Cursor, etc.)
        |
        | MCP Protocol (HTTPS)
        v
  Sutram MCP Endpoint
    https://app.sutram.io/mcp
        |
        | Dual Key Authentication
        v
  Your Project (folders, files, content)

Se requieren dos API keys para cada conexion:

Clave	Proposito	Quien la crea	Donde encontrarla
Project Key (`sk_proj_...`)	Identifica el proyecto	El propietario del proyecto	Pagina del proyecto o configuracion del proyecto
User Key (`sk_user_...`)	Te identifica a ti	Cada usuario crea la suya	Configuracion de Usuario > API Key

Ambas claves deben ser validas, y debes ser un miembro activo del proyecto (no un observador) para conectarte.

Primeros pasos

Paso 1: Crea tu API Key personal

Ve a Settings (icono de engranaje en el menu superior derecho)
Haz clic en la tarjeta API Key
Haz clic en Create Key
Copia la clave inmediatamente — solo se mostrara una vez

Tu clave personal se ve asi: sk_user_zQD0BjH56nQhOgX3uxni...

Importante: Guarda tu clave de forma segura. Si la pierdes, puedes revocar la anterior y crear una nueva desde la misma pagina de configuracion.

Paso 2: Obtener la clave del proyecto

El propietario del proyecto debe primero habilitar el acceso remoto para el proyecto:

Ve a Settings > pestana Projects
Abre el menu desplegable (tres puntos) junto al proyecto
Haz clic en Enable Remote Access
Copia la clave del proyecto que aparece

Una vez habilitado el acceso remoto, cualquier miembro del proyecto (propietario, administrador o miembro) puede copiar la clave del proyecto:

Abre el proyecto
Haz clic en el icono de senal verde junto a la insignia de rol en el encabezado
Un modal mostrara la clave del proyecto — haz clic en el boton de copiar

La clave del proyecto se ve asi: sk_proj_ej8NWMisd2rJgMwAJ22T...

Configuracion de tu cliente de IA

Cada proyecto de Sutram debe tener su propia configuracion MCP local. Dado que la clave del proyecto esta vinculada a un proyecto especifico, el enfoque recomendado es crear una carpeta de trabajo dedicada para cada integracion y colocar el archivo .mcp.json alli.

Ejemplo: Si usas Sutram para almacenar examenes medicos, crea una carpeta local para ese flujo de trabajo:

~/projects/medical-exams/
└── .mcp.json          ← Sutram keys for your health project

Esto mantiene las credenciales en el contexto correcto y evita mezclar proyectos no relacionados.

Claude Code (CLI) — Recomendado

Crea un archivo .mcp.json en tu carpeta de trabajo:

{
  "mcpServers": {
    "sutram": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.sutram.io/mcp",
        "--header",
        "x-project-key: sk_proj_YOUR_PROJECT_KEY",
        "--header",
        "x-user-key: sk_user_YOUR_USER_KEY"
      ]
    }
  }
}

Nota: Claude Code aun no soporta type: "url" de forma nativa. La configuracion anterior usa mcp-remote como puente para conectarse via stdio. Esto requiere que Node.js (npx) este instalado. El paquete mcp-remote se descarga automaticamente en el primer uso.

Luego inicia Claude Code desde esa carpeta. Las herramientas de Sutram estaran disponibles solo en ese contexto.

Cursor

Crea un archivo .cursor/mcp.json en tu carpeta de trabajo:

{
  "mcpServers": {
    "sutram": {
      "type": "url",
      "url": "https://app.sutram.io/mcp",
      "headers": {
        "x-project-key": "sk_proj_YOUR_PROJECT_KEY",
        "x-user-key": "sk_user_YOUR_USER_KEY"
      }
    }
  }
}

Claude Desktop

Claude Desktop usa un archivo de configuracion global. Agrega una entrada para cada proyecto de Sutram, usando un nombre descriptivo para distinguirlos:

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

Si tu version de Claude Desktop soporta type: "url":

{
  "mcpServers": {
    "sutram-medical-exams": {
      "type": "url",
      "url": "https://app.sutram.io/mcp",
      "headers": {
        "x-project-key": "sk_proj_HEALTH_PROJECT_KEY",
        "x-user-key": "sk_user_YOUR_USER_KEY"
      }
    },
    "sutram-construction": {
      "type": "url",
      "url": "https://app.sutram.io/mcp",
      "headers": {
        "x-project-key": "sk_proj_WORK_PROJECT_KEY",
        "x-user-key": "sk_user_YOUR_USER_KEY"
      }
    }
  }
}

Si type: "url" no es reconocido, usa el puente mcp-remote en su lugar:

{
  "mcpServers": {
    "sutram-medical-exams": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://app.sutram.io/mcp",
        "--header",
        "x-project-key: sk_proj_HEALTH_PROJECT_KEY",
        "--header",
        "x-user-key: sk_user_YOUR_USER_KEY"
      ]
    }
  }
}

Reinicia Claude Desktop despues de guardar el archivo.

Consejo: La clave de usuario (sk_user_...) es la misma en todas las entradas — te identifica a ti. La clave del proyecto (sk_proj_...) cambia por proyecto.

Otros clientes MCP

Sutram usa el transporte MCP Streamable HTTP. Cualquier cliente compatible con MCP que soporte transporte HTTP puede conectarse usando:

Endpoint: https://app.sutram.io/mcp
Method: POST (JSON-RPC 2.0)
Authentication: Headers personalizados x-project-key y x-user-key
Protocol version: 2024-11-05

Para clientes que solo soportan transporte stdio, usa mcp-remote como puente:

npx -y mcp-remote https://app.sutram.io/mcp \
  --header "x-project-key: sk_proj_YOUR_PROJECT_KEY" \
  --header "x-user-key: sk_user_YOUR_USER_KEY"

Herramientas disponibles

Una vez conectado, tu asistente de IA tiene acceso a estas herramientas. Tambien puedes obtener esta lista programaticamente enviando la solicitud MCP estandar tools/list al endpoint del servidor.

Referencia rapida (A–Z)

#	Herramienta	Categoria	Descripcion
1	`sutram_add_enum_values`	Schema	Agrega nuevos valores a una definicion de metadata enum existente
2	`sutram_cancel_checkout`	Versioning	Cancela el checkout sin subir cambios
3	`sutram_checkin_file`	Versioning	Libera un archivo del checkout (check-in)
4	`sutram_checkout_file`	Versioning	Hace checkout de un archivo para edicion exclusiva
5	`sutram_confirm_upload`	Content	Paso 2 de la subida: confirma que el archivo fue subido a S3
6	`sutram_bulk_create_file_links`	File Links	Crea file links en masa desde una carpeta origen a una carpeta destino
7	`sutram_cancel_checkout`	Versioning	Cancela el checkout sin subir cambios
8	`sutram_checkin_file`	Versioning	Libera un archivo del checkout (check-in)
9	`sutram_checkout_file`	Versioning	Hace checkout de un archivo para edicion exclusiva
10	`sutram_confirm_upload`	Content	Paso 2 de la subida: confirma que el archivo fue subido a S3
11	`sutram_create_audio_link`	Content	Crea un enlace de audio (Spotify, SoundCloud, etc.)
12	`sutram_create_comment`	Comments	Crea un comentario a nivel de archivo o markdown en un elemento de contenido
13	`sutram_create_file_link`	File Links	Crea un file link (referencia simbolica) a un archivo existente
14	`sutram_create_folder`	Folders	Crea una nueva carpeta o ruta anidada
15	`sutram_create_new_version`	Versioning	Crea una nueva version a partir de un archivo publicado
16	`sutram_create_record`	Records	Crea un nuevo registro en una categoria
17	`sutram_create_video_link`	Content	Crea un enlace de video (YouTube, Vimeo, etc.)
18	`sutram_create_web_link`	Content	Crea un enlace web con titulo obtenido automaticamente
19	`sutram_delete`	Content	Elimina un elemento de contenido o carpeta
20	`sutram_delete_comment`	Comments	Elimina un comentario y todas sus respuestas
21	`sutram_delete_metadata`	Schema	Elimina una definicion de metadata
22	`sutram_delete_record`	Records	Elimina un registro
23	`sutram_delete_record_category`	Schema	Elimina una categoria de registros
24	`sutram_disable_versioning`	Versioning	Convierte el archivo de vuelta a referencia (solo lectura)
25	`sutram_enable_versioning`	Versioning	Convierte el archivo de referencia a editable
26	`sutram_force_release_lock`	Versioning	Libera forzosamente el checkout de otro usuario (solo propietario)
27	`sutram_get_comment_thread`	Comments	Obtiene un comentario con su hilo completo de respuestas
28	`sutram_get_folder`	Folders	Devuelve el contenido de una carpeta
29	`sutram_get_item`	Content	Obtiene detalles completos y URL de descarga de un elemento de contenido
30	`sutram_get_item_tag_keys`	Tags	Devuelve todas las claves de tags distintas usadas en elementos de contenido
31	`sutram_get_metadata_definitions`	Schema	Devuelve todas las definiciones de campos de metadata
32	`sutram_get_record_categories`	Schema	Devuelve todas las categorias de registros
33	`sutram_get_record_category_detail`	Schema	Devuelve una categoria con metadata completamente resuelta
34	`sutram_get_tag_keys`	Tags	Devuelve todas las claves de tags distintas usadas en carpetas
35	`sutram_list_comments`	Comments	Lista todos los comentarios de nivel superior en un elemento de contenido
36	`sutram_list_file_links_for_source`	File Links	Lista todos los file links que apuntan a un archivo origen
37	`sutram_list_file_links_in_folder`	File Links	Lista file links en una carpeta con detalles del archivo origen
38	`sutram_list_versions`	Versioning	Lista todas las versiones de un archivo
39	`sutram_move_contents`	Folders	Mueve todo el contenido de una carpeta a otra
40	`sutram_move_item`	Content	Mueve un solo elemento de contenido a otra carpeta
41	`sutram_project_info`	Project	Devuelve nombre, descripcion y configuracion del proyecto
42	`sutram_publish_version`	Versioning	Publica un archivo borrador, creando una instantanea de version
43	`sutram_remove_enum_values`	Schema	Elimina valores de una definicion de metadata enum
44	`sutram_rename`	Content	Renombra un elemento de contenido o carpeta
45	`sutram_reply_to_comment`	Comments	Responde a un comentario de nivel superior existente
46	`sutram_request_upload`	Content	Paso 1 de la subida: devuelve una URL presignada de S3 PUT
47	`sutram_resolve_comment`	Comments	Resuelve o reabre un hilo de comentarios
48	`sutram_search_folders`	Tags	Busca carpetas por tag (condicion simple o AND)
49	`sutram_search_items`	Tags	Busca elementos de contenido por tag
50	`sutram_set_folder_tags`	Tags	Establece tags clave-valor en una carpeta
51	`sutram_set_item_tags`	Tags	Establece tags clave-valor en un elemento de contenido
52	`sutram_undo_checkin`	Versioning	Deshace el ultimo check-in, restaurando la version anterior
53	`sutram_update_record`	Records	Actualiza la metadata de un registro
54	`sutram_upload_modified_file`	Versioning	Reemplaza el contenido del archivo durante el checkout
55	`sutram_upsert_metadata`	Schema	Crea o actualiza una definicion de campo de metadata
56	`sutram_upsert_record_category`	Schema	Crea o actualiza una categoria de registros

Categorias: Project (1) · Folders (3) · Content (8) · File Links (4) · Tags (6) · Versioning (12) · Comments (6) · Schema (8) · Records (4)

Las secciones a continuacion describen cada herramienta en detalle, organizadas por funcionalidad.

sutram_project_info

Devuelve informacion sobre el proyecto actual.

Parametros: Ninguno

Ejemplo de respuesta:

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

sutram_get_folder

Explora el contenido de una carpeta (subcarpetas, archivos y enlaces). Omite folder_id para listar el contenido de la raiz.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`folder_id`	string	No	UUID de la carpeta. Omitir para la raiz.

Ejemplo de respuesta:

{
  "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

Crea una nueva carpeta. Soporta la creacion de jerarquias anidadas en una sola llamada.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`name`	string	Si*	Nombre de la carpeta (para crear una sola carpeta)
`path`	string	Si*	Ruta separada por barras para creacion anidada (ej., `"A/B/C"`)
`parent_folder_id`	string	No	UUID de la carpeta padre. Omitir para nivel raiz.
`tags`	object	No	Tags clave-valor de forma libre (ej., `{"patient": "John", "exam_type": "USG"}`). Al usar `path`, los tags se aplican solo a la carpeta mas profunda (hoja).

*Usa name (carpeta individual) o path (jerarquia anidada), no ambos.

Creacion anidada: Al usar path, las carpetas intermedias se crean automaticamente. Si alguna carpeta en la ruta ya existe, se reutiliza — la operacion es idempotente.

Ejemplo — carpeta individual:

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

Ejemplo — jerarquia anidada con tags:

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

Esto crea tres carpetas en una sola llamada y devuelve la mas profunda (2024-12-12) con los tags especificados.

sutram_request_upload

Paso 1 del flujo de subida directa. Valida el archivo y devuelve una URL presignada de S3 PUT. El archivo se sube directamente a S3 por el cliente — ningun dato pasa a traves de los servidores web de Sutram.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`filename`	string	Si	Nombre del archivo con extension (ej., `report.pdf`)
`file_size`	integer	Si	Tamano del archivo en bytes
`content_type`	string	No	Tipo MIME. Se detecta automaticamente de la extension si se omite.
`folder_id`	string	No	UUID de la carpeta destino. Omitir para la raiz.

Ejemplo de respuesta:

{
  "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

Paso 2 del flujo de subida directa. Llama a este despues de que el archivo haya sido subido a la URL presignada. Verifica que el objeto S3 existe, crea el registro del archivo, actualiza el uso de almacenamiento y encola la compresion si corresponde.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`file_id`	string	Si	UUID del archivo de `sutram_request_upload`
`s3_key`	string	Si	Clave S3 de `sutram_request_upload`
`filename`	string	Si	Nombre original del archivo con extension
`content_type`	string	Si	Tipo MIME del archivo
`file_size`	integer	Si	Tamano del archivo en bytes
`folder_id`	string	No	UUID de la carpeta destino (debe coincidir con la solicitud)

Ejemplo de respuesta:

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

Ejemplo completo del flujo de subida:

# 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

Crea un enlace web en el proyecto. Sutram obtiene automaticamente el titulo de la pagina y el favicon de la URL.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`url`	string	Si	URL de la pagina web (debe ser http o https)
`name`	string	No	Nombre para mostrar. Se obtiene automaticamente del titulo de la pagina si se omite.
`folder_id`	string	No	UUID de la carpeta destino. Omitir para la raiz.

Ejemplo de respuesta:

{
  "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

Crea un enlace de video en el proyecto. Soporta YouTube, Vimeo, DailyMotion, Wistia, Loom y TikTok. Detecta automaticamente la plataforma y extrae el ID del video de la URL.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`url`	string	Si	URL del video (ej., `https://www.youtube.com/watch?v=...`)
`name`	string	No	Nombre para mostrar. Por defecto usa la URL si se omite.
`folder_id`	string	No	UUID de la carpeta destino. Omitir para la raiz.

Ejemplo de respuesta:

{
  "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

Crea un enlace de audio en el proyecto. Soporta Spotify, SoundCloud, Apple Podcasts y mas. Detecta automaticamente la plataforma y extrae el ID del audio de la URL.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`url`	string	Si	URL del contenido de audio (ej., `https://open.spotify.com/track/...`)
`name`	string	No	Nombre para mostrar. Por defecto usa la URL si se omite.
`folder_id`	string	No	UUID de la carpeta destino. Omitir para la raiz.

Ejemplo de respuesta:

{
  "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

Crea un file link (referencia simbolica) a un archivo existente en el proyecto. El enlace aparece como una referencia de solo lectura sin duplicar almacenamiento ni versionamiento. El origen debe ser un archivo (no un enlace ni otro file link). Si el archivo origen se elimina, todos sus file links se eliminan automaticamente.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`source_content_item_id`	string	Si	UUID del elemento de contenido del archivo origen al que se enlaza
`name`	string	No	Nombre para mostrar (por defecto el nombre del archivo origen)
`folder_id`	string	No	UUID de la carpeta destino (omitir para la raiz)
`description`	string	No	Descripcion del file link

Ejemplo de solicitud:

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

Ejemplo de respuesta:

{
  "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

Crea file links en masa para todos los archivos (o un subconjunto filtrado) en una carpeta origen, colocandolos en una carpeta destino. Omite automaticamente los archivos que ya tienen un enlace en la carpeta destino (deduplicacion). Ideal para flujos de trabajo como enlazar multiples archivos de examenes a una carpeta centralizada de reportes.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`source_folder_id`	string	Si	UUID de la carpeta origen que contiene los archivos a enlazar
`target_folder_id`	string	Si	UUID de la carpeta destino donde se crearan los file links
`name_pattern`	string	No	Filtro de subcadena (sin distincion de mayusculas/minusculas) sobre los nombres de archivos origen. Solo se enlazan los archivos que coincidan.
`recursive`	boolean	No	Incluir archivos de subcarpetas de la carpeta origen (por defecto: false)

Ejemplo de solicitud:

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

Ejemplo de respuesta:

{
  "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-..."
    }
  ]
}

Consejo: Ejecutar el mismo comando nuevamente omitira todos los archivos previamente enlazados ("created": 0, "skipped": 7), lo que hace seguro volver a ejecutarlo.

sutram_list_file_links_for_source

Lista todos los file links que apuntan a un archivo origen dado. Responde la pregunta: "donde esta referenciado este archivo?" Devuelve cada enlace con su ruta de carpeta.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`source_content_item_id`	string	Si	UUID del elemento de contenido del archivo origen

Ejemplo de solicitud:

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

Ejemplo de respuesta:

{
  "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

Lista todos los file links en una carpeta, enriquecidos con detalles del archivo origen (nombre, tipo de contenido, tamano de archivo, ruta de carpeta). A diferencia de sutram_get_folder, esto proporciona informacion completa sobre el archivo origen al que apunta cada enlace.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`folder_id`	string	No	UUID de la carpeta (omitir para la raiz)

Ejemplo de solicitud:

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

Ejemplo de respuesta:

{
  "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

Obtiene los detalles completos de un elemento de contenido por ID. Para archivos, devuelve metadata y una URL de descarga presignada. Para enlaces (web, video, audio, file_link), devuelve la URL, informacion de la plataforma y metadata.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`content_item_id`	string	Si	UUID del elemento de contenido

Ejemplo de respuesta (archivo):

{
  "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-..."
}

Ejemplo de respuesta (enlace web):

{
  "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"
}

Ejemplo de respuesta (enlace de video):

{
  "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

Elimina un elemento de contenido (archivo, enlace web, enlace de video, enlace de audio) o carpeta del proyecto.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`item_id`	string	Si	UUID del elemento de contenido o carpeta
`item_type`	string	Si	`"content_item"` o `"folder"`. Usa `"content_item"` para cualquier tipo de contenido (archivos, enlaces web, enlaces de video, enlaces de audio).

sutram_rename

Renombra un elemento de contenido (archivo, enlace web, enlace de video, enlace de audio) o carpeta.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`item_id`	string	Si	UUID del elemento de contenido o carpeta
`item_type`	string	Si	`"content_item"` o `"folder"`. Usa `"content_item"` para cualquier tipo de contenido (archivos, enlaces web, enlaces de video, enlaces de audio).
`new_name`	string	Si	Nuevo nombre (para archivos, incluir la extension)

sutram_move_contents

Mueve todo el contenido (subcarpetas y archivos) de una carpeta origen a una carpeta destino. La carpeta origen queda vacia pero no se elimina. Los conflictos de nombre se manejan automaticamente.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`source_folder_id`	string	Si	UUID de la carpeta origen a vaciar
`target_folder_id`	string	Si	UUID de la carpeta destino que recibira el contenido

Manejo de conflictos de nombre: Si una subcarpeta o archivo con el mismo nombre ya existe en la carpeta destino, Sutram renombra automaticamente el elemento movido agregando un sufijo numerico: Exams se convierte en Exams (1), report.pdf se convierte en report (1).pdf, y asi sucesivamente.

Reglas de validacion:

Origen y destino deben ser carpetas diferentes
El destino no puede ser una subcarpeta del origen (previene movimientos circulares)
Ambas carpetas deben existir en el proyecto actual

Ejemplo de respuesta:

{
  "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

Mueve un solo elemento de contenido (archivo o enlace) a otra carpeta. Los conflictos de nombre se manejan automaticamente.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`content_item_id`	string	Si	UUID del elemento de contenido a mover
`target_folder_id`	string/null	No	UUID de la carpeta destino (null para la raiz)

Manejo de conflictos de nombre: Si un archivo con el mismo nombre ya existe en la carpeta destino, Sutram renombra automaticamente el archivo movido agregando un sufijo numerico: report.pdf se convierte en report (1).pdf, y asi sucesivamente.

Ejemplo de respuesta (sin conflicto):

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

Ejemplo de respuesta (con renombramiento):

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

sutram_set_folder_tags

Establece tags clave-valor de forma libre en una carpeta. Reemplaza todos los tags existentes. Envia {} para limpiar todos los tags.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`folder_id`	string	Si	UUID de la carpeta
`tags`	object	Si	Tags clave-valor a establecer. Envia `{}` para limpiar todos los tags.

Limites: Maximo 50 tags por carpeta. Clave maximo 100 caracteres, valor maximo 500 caracteres.

Semantica: Esta es una operacion PUT — reemplaza todos los tags existentes. Para agregar un tag sin eliminar los demas, primero lee los tags actuales (via sutram_get_folder), fusiona tus cambios, luego llama a sutram_set_folder_tags con el conjunto completo.

Ejemplo — establecer tags:

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

Ejemplo — limpiar todos los tags:

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

Ejemplo de respuesta:

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

sutram_search_folders

Busca carpetas por tag. Soporta condiciones simples o multiples AND. Toda la comparacion es sin distincion de mayusculas/minusculas tanto para claves como valores. Los valores soportan coincidencia de subcadena (ej., "orto" coincide con "Ortopedia"). Usa folder_id para restringir la busqueda a descendientes de una carpeta especifica.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`tag_name`	string	No*	Clave del tag a buscar (modo condicion simple). Sin distincion de mayusculas/minusculas.
`tag_value`	string	No	Valor a buscar (modo condicion simple). Coincidencia de subcadena, sin distincion de mayusculas/minusculas.
`conditions`	array	No*	Multiples condiciones AND. Cada objeto tiene `key` (requerido) y `value` (opcional).
`folder_id`	string	No	UUID de la carpeta para acotar la busqueda. Solo busca descendientes de esta carpeta.

*Usa tag_name (condicion simple) o conditions (multiples condiciones AND).

Comportamiento de busqueda:

Coincidencia de clave: Coincidencia exacta sin distincion de mayusculas/minusculas ("Patient" coincide con "patient")
Coincidencia de valor: Coincidencia de subcadena sin distincion de mayusculas/minusculas ("orto" coincide con "Ortopedia", "joão" coincide con "João Silva")
Sin valor: Cuando se omite el valor, coincide con cualquier carpeta que tenga la clave sin importar el valor
Multiples condiciones: Todas las condiciones deben coincidir (logica AND)

Ejemplo — encontrar todas las carpetas con tag "patient":

{ "tag_name": "patient" }

Ejemplo — encontrar carpetas para un paciente especifico (coincidencia de subcadena):

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

Esto coincide con carpetas donde el tag "patient" contiene "joão" (ej., "João Silva", "João Pedro").

Ejemplo — busqueda AND con multiples condiciones:

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

Esto devuelve solo carpetas que coinciden con ambas condiciones.

Ejemplo — buscar solo dentro de una jerarquia de carpetas especifica:

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

Ejemplo de respuesta:

{
  "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

Devuelve todas las claves de tags distintas usadas en las carpetas del proyecto. Util para descubrir que tags estan disponibles antes de realizar una busqueda. Usa folder_id para restringir a descendientes de una carpeta especifica.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`folder_id`	string	No	UUID de la carpeta para acotar. Solo devuelve claves de descendientes de esta carpeta.

Ejemplo — obtener todas las claves de tags en el proyecto:

{}

Ejemplo — obtener claves de tags dentro de una jerarquia de carpetas:

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

Ejemplo de respuesta:

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

sutram_set_item_tags

Establece tags clave-valor de forma libre en un elemento de contenido. Reemplaza todos los tags existentes. Envia {} para limpiar todos los tags.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`content_item_id`	string	Si	UUID del elemento de contenido
`tags`	object	Si	Tags clave-valor a establecer. Envia `{}` para limpiar todos los tags.

Limites: Maximo 50 tags por elemento. Clave maximo 100 caracteres, valor maximo 500 caracteres.

Semantica: Esta es una operacion PUT — reemplaza todos los tags existentes. Para agregar un tag sin eliminar los demas, primero lee los tags actuales (via sutram_get_item), fusiona tus cambios, luego llama a sutram_set_item_tags con el conjunto completo.

Ejemplo — establecer tags:

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

Ejemplo — limpiar todos los tags:

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

Ejemplo de respuesta:

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

sutram_search_items

Busca elementos de contenido por tag. Soporta condiciones simples o multiples AND. Toda la comparacion es sin distincion de mayusculas/minusculas tanto para claves como valores. Los valores soportan coincidencia de subcadena (ej., "neuro" coincide con "Neurologia"). Usa folder_id para restringir la busqueda a una carpeta especifica, y type para filtrar por tipo de contenido.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`tag_name`	string	No*	Clave del tag a buscar (modo condicion simple). Sin distincion de mayusculas/minusculas.
`tag_value`	string	No	Valor a buscar (modo condicion simple). Coincidencia de subcadena, sin distincion de mayusculas/minusculas.
`conditions`	array	No*	Multiples condiciones AND. Cada objeto tiene `key` (requerido) y `value` (opcional).
`folder_id`	string	No	UUID de la carpeta para acotar la busqueda.
`type`	string	No	Filtro por tipo de contenido: `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

*Usa tag_name (condicion simple) o conditions (multiples condiciones AND).

Ejemplo — encontrar todos los elementos con tag "topic":

{ "tag_name": "topic" }

Ejemplo — encontrar elementos para un tema especifico (coincidencia de subcadena):

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

Ejemplo — busqueda AND con multiples condiciones:

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

Ejemplo — buscar solo enlaces de video en una carpeta especifica:

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

Ejemplo de respuesta:

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

sutram_get_item_tag_keys

Devuelve todas las claves de tags distintas usadas en los elementos de contenido del proyecto. Util para descubrir que tags estan disponibles antes de realizar una busqueda. Usa folder_id para restringir a una carpeta especifica, y type para filtrar por tipo de contenido.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`folder_id`	string	No	UUID de la carpeta para acotar.
`type`	string	No	Filtro por tipo de contenido: `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

Ejemplo — obtener todas las claves de tags de contenido en el proyecto:

{}

Ejemplo — obtener claves de tags solo para enlaces de video:

{ "type": "video_link" }

Ejemplo de respuesta:

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

Versionamiento de archivos

Sutram soporta un flujo de trabajo completo de versionamiento para archivos via MCP. Esto permite que los asistentes de IA habiliten el control de versiones, hagan checkout de archivos para edicion exclusiva, suban modificaciones y publiquen versiones.

Flujo de trabajo

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)

Herramientas de versionamiento

Herramienta	Descripcion	Permiso
`sutram_enable_versioning`	Convierte archivo de referencia a editable (inicia versionamiento)	Owner, Member
`sutram_disable_versioning`	Convierte archivo de vuelta a referencia (detiene versionamiento)	Owner, Member
`sutram_checkout_file`	Hace checkout del archivo para edicion exclusiva	Owner, Admin, Member
`sutram_checkin_file`	Libera el bloqueo de checkout	Usuario que hizo checkout
`sutram_cancel_checkout`	Cancela checkout sin cambios	Usuario que hizo checkout
`sutram_force_release_lock`	Libera forzosamente el checkout de otro usuario	Solo Owner
`sutram_publish_version`	Publica un archivo borrador, creando una instantanea de version	Solo Owner
`sutram_create_new_version`	Inicia nueva version desde archivo publicado	Solo Owner
`sutram_undo_checkin`	Deshace el ultimo check-in, restaura la version anterior	Ultimo usuario que hizo checkin
`sutram_list_versions`	Lista todas las versiones publicadas con URLs de descarga	Cualquier miembro
`sutram_upload_modified_file`	Reemplaza el contenido del archivo durante el checkout	Usuario que hizo checkout

Parametros

Todas las herramientas de versionamiento requieren content_item_id (UUID del elemento de contenido).

sutram_upload_modified_file adicionalmente requiere:

Parametro	Tipo	Descripcion
`s3_key`	string	Clave S3 de `sutram_request_upload`
`file_name`	string	Nombre del archivo con extension
`file_size`	integer	Tamano del archivo en bytes
`content_type`	string	Tipo MIME

Ejemplo: Flujo completo de versionamiento

// 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 }

Categorias de registros y registros

Sutram soporta registros estructurados con esquemas de metadata y slugs generados automaticamente. Esto permite que los asistentes de IA definan campos de metadata, creen categorias de registros y gestionen registros programaticamente.

Requisito de plan: Las herramientas de gestion de registros y esquemas requieren un plan con la funcionalidad de Records habilitada (Plus o superior). Las herramientas de solo lectura (sutram_get_metadata_definitions, sutram_get_record_categories, sutram_get_record_category_detail) estan disponibles en todos los planes.

Conceptos

Definiciones de metadata — Esquemas de campos que definen los tipos, etiquetas y valores permitidos para campos de metadata (ej., "language" como enum con valores "PT", "EN", "ES").
Categorias de registros — Plantillas que definen que campos de metadata usa un registro, su orden, como se calcula la base numerica (computed_from) y como se compone el slug (nombre del registro) (slug_from).
Registros — Carpetas creadas con una categoria, metadata validada y un slug generado automaticamente.

Generacion de slug

Los registros tienen un slug generado automaticamente (usado como nombre del registro). El slug se construye en dos pasos:

Base numerica — Determinada por las entradas computed_from en un tag de metadata calculado. Esto define que valores de campo forman la clave de unicidad para la numeracion secuencial.
Composicion del slug — Determinada por las entradas slug_from en la categoria. Esto define que valores de campo (incluido el tag calculado) componen el slug final.

Sin slug_from (compatible con versiones anteriores): slug = number_base + separator + sequence_number (ej., 0100-200-001).

Con slug_from: el slug se compone a partir de los campos referenciados en orden (ej., MD-3010.95-0000-000-SWA-001).

Herramientas de esquema

Herramienta	Descripcion	Permiso
`sutram_get_metadata_definitions`	Lista todas las definiciones de metadata	Cualquier miembro
`sutram_get_record_categories`	Lista todas las categorias de registros	Cualquier miembro
`sutram_get_record_category_detail`	Categoria con metadata completamente resuelta (etiquetas, tipos, valores permitidos)	Cualquier miembro
`sutram_upsert_metadata`	Crea o actualiza una definicion de metadata	Solo Owner
`sutram_delete_metadata`	Elimina una definicion de metadata (falla si esta en uso)	Solo Owner
`sutram_add_enum_values`	Agrega valores a una definicion enum (fusiona, deduplica, ordena)	Solo Owner
`sutram_remove_enum_values`	Elimina valores de una definicion enum por codigo	Solo Owner
`sutram_upsert_record_category`	Crea o actualiza una categoria de registros	Solo Owner
`sutram_delete_record_category`	Elimina una categoria de registros	Solo Owner

Herramientas CRUD de registros

Herramienta	Descripcion	Permiso
`sutram_create_record`	Crea un registro con categoria, metadata y slug generado automaticamente	Owner, Admin, Member
`sutram_update_record`	Actualiza la metadata de un registro (recalcula el slug si es necesario)	Owner, Admin, Member
`sutram_delete_record`	Elimina un registro y todo su contenido recursivamente	Owner, Admin, Member

sutram_get_metadata_definitions

Devuelve todas las definiciones de metadata del proyecto. Cada definicion tiene una clave y propiedades: label, type (text, enum, boolean, date, computed) y opcionalmente values, depends_on, values_map.

Parametros: Ninguno

sutram_get_record_categories

Devuelve todas las categorias de registros del proyecto. Cada categoria define que campos de metadata usa un registro, la configuracion del slug y el ordenamiento.

Parametros: Ninguno

sutram_get_record_category_detail

Devuelve una categoria de registros con metadata completamente resuelta (etiquetas, tipos, valores permitidos de las definiciones). Usa esto para entender que campos se necesitan antes de crear un registro.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`category_id`	string	Si	ID de la categoria de registros

sutram_upsert_metadata

Crea o actualiza una definicion de metadata (esquema de campo). Para tipos enum, proporciona el array completo de values. Para enums grandes, prefiere sutram_add_enum_values para adiciones incrementales.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`key`	string	Si	Clave unica (snake_case, ej., `"specialty"`)
`definition`	object	Si	Definicion con `label`, `type` y campos opcionales

Tipos soportados: text, enum, boolean, date, computed.

Ejemplo — crear un enum simple:

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

sutram_delete_metadata

Elimina una definicion de metadata. Falla si la definicion esta actualmente en uso por alguna categoria de registros.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`key`	string	Si	Clave de la definicion a eliminar

sutram_add_enum_values

Agrega valores a una definicion de metadata enum existente. Los nuevos valores se fusionan con los existentes — los duplicados (por codigo) se omiten. Los valores se ordenan por codigo despues de la fusion. Usa esto en lugar de sutram_upsert_metadata cuando trabajes con enums grandes para evitar enviar el array completo de valores.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`key`	string	Si	Clave de la definicion enum
`values`	array	Si	Array de objetos `{label, code}` a agregar

Ejemplo — agregar valores a un enum existente con 800+ elementos:

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

Ejemplo de respuesta:

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

sutram_remove_enum_values

Elimina valores de una definicion de metadata enum existente por sus codigos.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`key`	string	Si	Clave de la definicion enum
`codes`	array	Si	Array de cadenas de codigo a eliminar

Ejemplo:

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

Ejemplo de respuesta:

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

sutram_upsert_record_category

Crea o actualiza una categoria de registros. La metadata debe referenciar definiciones existentes. Usa computed_from en una entrada de metadata para definir la base numerica (unicidad). Usa slug_from a nivel de categoria para definir como se compone el slug (nombre del registro).

Parametros:

Parametro	Tipo	Requerido	Descripcion
`category_id`	string	Si	ID unico de la categoria (snake_case)
`category`	object	Si	Definicion de la categoria (ver campos abajo)

Campos de la categoria:

Campo	Tipo	Requerido	Descripcion
`name`	string	Si	Nombre para mostrar de la categoria
`metadata`	array	Si	Array de referencias a campos de metadata (ver abajo)
`slug_separator`	string	No	Separador entre partes del slug (por defecto: `"-"`)
`slug_from`	array	No	Define la composicion del slug. Cada entrada tiene `key` y `use` (`"code"` o `"label"`). Si se omite, slug = number_base + separator + sequence_number

Campos de entrada de metadata:

Campo	Tipo	Requerido	Descripcion
`key`	string	Si	Clave de una definicion de metadata existente
`required`	boolean	No	Si este campo es obligatorio (por defecto: false)
`order`	integer	No	Orden de visualizacion (base 0)
`computed_from`	array	No	Solo para tags calculados. Define la base numerica. Cada entrada tiene `key` y `use` (`"code"` o `"label"`)
`sequence_digits`	integer	No	Solo para tags calculados. Digitos para el numero de secuencia (2-4, por defecto: 2)

Ejemplo — categoria con slug_from (estilo N-1710):

{
  "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" }
    ]
  }
}

En este ejemplo:

Base numerica (de computed_from): MD-3010.95-0000-000 — determina la unicidad secuencial
Numero codificado: 001 (siguiente secuencia disponible)
Slug (de slug_from): MD-3010.95-0000-000-SWA-001 — incluye document_origin + secuencia

Ejemplo — categoria simple sin slug_from (compatible con versiones anteriores):

{
  "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": "-"
  }
}

Sin slug_from, el slug es automaticamente: {number_base}{separator}{sequence} (ej., CARDIO-001).

sutram_delete_record_category

Elimina una categoria de registros.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`category_id`	string	Si	ID de la categoria a eliminar

sutram_create_record

Crea un registro con una categoria, metadata validada y slug generado automaticamente. El slug se calcula a partir de la definicion slug_from de la categoria, o a partir de computed_from (base numerica) + separador + numero de secuencia. Usa sutram_get_record_category_detail primero para ver los campos requeridos.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`category_id`	string	Si	ID de la categoria de registros
`metadata`	object	Si	Pares clave-valor que coinciden con los campos de metadata de la categoria
`parent_folder_id`	string	No	UUID de la carpeta padre (omitir para la raiz)
`name`	string	No	Nombre personalizado (por defecto usa el slug generado automaticamente)

Ejemplo:

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

La respuesta incluye el slug calculado y el numero de secuencia:

{
  "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

Actualiza la metadata de un registro. Recalcula la base numerica y el slug cuando cambian los campos de metadata referenciados por computed_from o slug_from.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`record_id`	string	Si	UUID del registro (carpeta)
`metadata`	object	Si	Pares clave-valor actualizados
`name`	string	No	Nuevo nombre (opcional)

sutram_delete_record

Elimina un registro y todo su contenido (subcarpetas y archivos) recursivamente. Esta accion no se puede deshacer.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`record_id`	string	Si	UUID del registro (carpeta) a eliminar

Ejemplo: Flujo de trabajo completo de registros

// 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", ... } }

Observa como:

La base numerica PT-0100 (de computed_from: language + area) determina la unicidad secuencial
El slug PT-0100-SWA-001 (de slug_from) incluye origin + el numero de secuencia
El segundo registro obtiene la secuencia 002 porque comparte la misma base numerica PT-0100

Comentarios de documentos

Los asistentes de IA pueden listar, crear, responder, resolver y eliminar comentarios en archivos del proyecto. Los comentarios creados via MCP aparecen en tiempo real en la interfaz web y viceversa, gracias a la transmision PubSub.

Restriccion de tipo de posicion: Via MCP, la IA solo puede crear comentarios file_level (comentario sobre todo el archivo) o markdown (anclado a texto en archivos markdown). Los tipos de posicion que requieren coordenadas de GUI (pdf_page, aps_3d, aps_2d, image) se pueden leer pero no crear via MCP.

Herramientas de comentarios

Herramienta	Descripcion	Permiso
`sutram_list_comments`	Lista todos los comentarios de nivel superior en un elemento de contenido	Cualquier miembro
`sutram_get_comment_thread`	Obtiene un comentario con su hilo completo de respuestas	Cualquier miembro
`sutram_create_comment`	Crea un comentario a nivel de archivo o markdown	Cualquier miembro
`sutram_reply_to_comment`	Responde a un comentario de nivel superior	Cualquier miembro
`sutram_resolve_comment`	Resuelve o reabre un hilo de comentarios	Cualquier miembro
`sutram_delete_comment`	Elimina un comentario y todas sus respuestas	Autor, Owner o Admin

sutram_list_comments

Lista todos los comentarios de nivel superior en un elemento de contenido. Devuelve el contenido del comentario, autor, tipo de posicion, estado de resolucion y conteo de respuestas.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`content_item_id`	string	Si	UUID del elemento de contenido
`include_resolved`	boolean	No	Si se incluyen comentarios resueltos (por defecto: true)

Ejemplo:

{
  "content_item_id": "abc-123"
}

Respuesta:

{
  "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

Obtiene un solo comentario con su hilo completo de respuestas, estado de resolucion y detalles del autor.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`comment_id`	string	Si	UUID del comentario

Respuesta:

{
  "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

Crea un comentario en un elemento de contenido. La IA puede crear comentarios file_level (por defecto) o markdown.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`content_item_id`	string	Si	UUID del elemento de contenido
`content`	string	Si	Texto del comentario
`position_type`	string	No	`"file_level"` (por defecto) o `"markdown"`
`text_anchor`	object	No	Para markdown: `{exact_text, prefix, suffix}`
`original_text_snippet`	string	No	Para markdown: el fragmento de texto seleccionado

Ejemplo — comentario a nivel de archivo:

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

Ejemplo — comentario markdown anclado a texto:

{
  "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

Responde a un comentario de nivel superior existente. Las respuestas no pueden anidarse (no se puede responder a una respuesta).

Parametros:

Parametro	Tipo	Requerido	Descripcion
`comment_id`	string	Si	UUID del comentario de nivel superior
`content`	string	Si	Texto de la respuesta

Ejemplo:

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

sutram_resolve_comment

Resuelve o reabre un hilo de comentarios. Los comentarios resueltos indican que el problema ha sido atendido.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`comment_id`	string	Si	UUID del comentario
`action`	string	Si	`"resolve"` o `"reopen"`

Ejemplo:

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

sutram_delete_comment

Elimina un comentario y todas sus respuestas. Solo el autor del comentario o el propietario/administrador del proyecto pueden eliminar.

Parametros:

Parametro	Tipo	Requerido	Descripcion
`comment_id`	string	Si	UUID del comentario

Ejemplo: Flujo de trabajo completo de comentarios

// 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, ... } }

Todos los cambios de comentarios se transmiten en tiempo real a los usuarios que estan viendo el mismo documento en la interfaz web.

Limitaciones

Las siguientes operaciones aun no estan disponibles via MCP y deben realizarse a traves de la interfaz web de Sutram. Se agregaran en futuras versiones:

Compartir: No se pueden generar enlaces para compartir
Comentarios posicionados: Crear comentarios anclados a paginas PDF, coordenadas CAD o posiciones en imagenes requiere la GUI web

Permisos

Tu acceso MCP respeta los mismos permisos que la interfaz web:

Rol	Explorar	Subir/Crear	Mover	Eliminar	Versionamiento	Esquema de registros	Registros	Comentarios
Owner	Si	Si	Si	Si	Completo (publicar, liberar forzosamente)	Completo (CRUD de definiciones y categorias)	CRUD	Completo (listar, crear, responder, resolver, eliminar cualquiera)
Admin	Si	Si	Si	Si	Checkout/checkin	Solo lectura	CRUD	Completo (listar, crear, responder, resolver, eliminar cualquiera)
Member	Si	Si	Si	Si	Habilitar/deshabilitar, checkout/checkin	Solo lectura	CRUD	Listar, crear, responder, resolver, eliminar propios
Viewer	Sin acceso MCP	—	—	—	—	—	—	—

Los observadores no pueden usar acceso remoto. Si necesitas acceso MCP, pide al propietario del proyecto que actualice tu rol.

Seguridad

Las claves son independientes: Revocar una clave de usuario no afecta a otros usuarios. Revocar una clave de proyecto deshabilita el acceso remoto para todos en ese proyecto.
Una clave de proyecto por proyecto: Solo existe una clave de proyecto activa a la vez. Regenerarla invalida la anterior.
Las claves nunca se almacenan en texto plano: Las claves de proyecto estan encriptadas. Las claves de usuario tienen hash — no se pueden recuperar despues de la creacion.
Seguimiento de actividad: Cada clave registra cuando fue usada por ultima vez.
Solo HTTPS: Todas las conexiones MCP usan HTTPS encriptado.

Revocar acceso

Para revocar tu clave personal:

Ve a Settings > API Key
Haz clic en "Revoke Key"
Crea una nueva si es necesario

Para deshabilitar el acceso remoto de un proyecto (solo propietario):

Ve a Settings > Projects
Abre el menu desplegable del proyecto
Haz clic en "Remote Access"
Haz clic en "Revoke Key"

Solucion de problemas

"Authentication failed"

Verifica que ambas claves sean correctas y no hayan sido revocadas
Asegurate de ser un miembro activo del proyecto
Los observadores no pueden usar acceso remoto — verifica tu rol en la pagina del proyecto

"Project key not available"

La clave del proyecto puede haber sido revocada por el propietario
Pide al propietario del proyecto que la regenere desde la configuracion del proyecto

"Storage quota exceeded"

Se alcanzo el limite de almacenamiento de tu cuenta
Elimina archivos que no uses o actualiza tu plan

Las herramientas no aparecen en Claude Code

Claude Code aun no soporta type: "url" — usa la configuracion con el puente mcp-remote (ver Configuracion de Claude Code)
Asegurate de que Node.js este instalado (npx debe estar disponible en tu PATH)
Verifica que el archivo .mcp.json este en la carpeta donde inicias Claude Code

Las herramientas no aparecen en Claude Desktop

Reinicia Claude Desktop despues de editar el archivo de configuracion
Verifica que la sintaxis JSON sea valida (sin comas finales, comillas correctas)
Verifica que la URL del endpoint sea correcta
Si type: "url" no funciona, prueba la configuracion con el puente mcp-remote (ver Configuracion de Claude Desktop)

Tiempo de espera de conexion agotado

Verifica tu conexion a internet
Verifica que el servicio de Sutram sea accesible en https://sutram.io

Tipos de archivos soportados

Sutram detecta automaticamente los tipos MIME a partir de las extensiones de archivo. Formatos comunes soportados:

Categoria	Extensiones
Imagenes	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`
Documentos	`.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`
Texto	`.txt`, `.csv`, `.json`, `.xml`, `.md`
Media	`.mp4`, `.mp3`, `.wav`
Archivos comprimidos	`.zip`
CAD	`.dwg`, `.dxf`, `.rvt`, `.ifc`

Los archivos con extensiones no reconocidas se suben como application/octet-stream.

Plataformas de enlaces soportadas

Plataformas de video

YouTube, Vimeo, DailyMotion, Wistia, Loom y TikTok. La plataforma se detecta automaticamente de la URL, y las miniaturas se extraen cuando estan disponibles.

Plataformas de audio

Spotify, SoundCloud, Apple Podcasts, Anchor y otras. La plataforma se detecta automaticamente de la URL.

Enlaces web

Cualquier URL HTTP/HTTPS valida. El titulo de la pagina, descripcion y favicon se obtienen automaticamente.

Ejemplos

Migrar examenes medicos desde portales hospitalarios

"Descarga mi examen de ecografia del portal del hospital y organizalo en Sutram bajo la carpeta del medico solicitante."

El asistente de IA:

Accede al portal del hospital (via navegador)
Descarga el reporte PDF y los archivos de imagen
Usa sutram_create_folder para construir la estructura de carpetas en una sola llamada: Nombre del Doctor / Tipo de Examen / AAAA-MM-DD
Usa sutram_request_upload + sutram_confirm_upload para subir cada archivo directamente a S3
Limpia los archivos locales temporales

Este flujo de trabajo asegura que los datos medicos esten correctamente organizados y que ningun archivo sensible permanezca en la computadora local.

Subir un archivo local

"Sube el archivo report.pdf de mi escritorio a la carpeta 'Reports' en Sutram."

Claude leera el archivo, usara sutram_get_folder para encontrar la carpeta "Reports", luego sutram_request_upload para obtener una URL presignada, subira el archivo directamente a S3 via HTTP PUT, y llamara a sutram_confirm_upload para finalizar.

Organizar contenido del proyecto

"Crea una estructura de carpetas para nuestro proyecto de construccion: Planos, Reportes y Fotos. Luego sube estas fotos del sitio."

Claude usara sutram_create_folder para cada carpeta de nivel superior, luego sutram_request_upload + sutram_confirm_upload para subir cada foto a la carpeta correcta.

Limpiar archivos viejos

"Elimina todos los archivos en la carpeta 'Temp'."

Claude usara sutram_get_folder para listar el contenido de la carpeta, luego sutram_delete para cada archivo.

Reorganizar estructura de carpetas

"Mueve todo el contenido de la carpeta '2024' a '2024-Archive' para liberar espacio en la vista principal."

Claude usara sutram_move_contents para transferir todas las subcarpetas y archivos de la carpeta origen a la destino en una sola operacion. Si algun elemento tiene nombres en conflicto, se renombran automaticamente con sufijos numericos.

Mover un archivo especifico

"Mueve el archivo 'contract.pdf' a la carpeta 'Legal'."

Claude usara sutram_get_folder para encontrar el archivo y la carpeta destino, luego sutram_move_item para mover el archivo. Si un archivo con el mismo nombre ya existe en la carpeta destino, se renombrara automaticamente (ej., contract (1).pdf).

Guardar un enlace web

"Guarda este articulo en mi proyecto: https://example.com/building-codes-2026"

Claude usara sutram_create_web_link con la URL. Sutram obtiene automaticamente el titulo de la pagina y el favicon, por lo que el enlace aparece con su nombre correcto en el proyecto.

Organizar referencias de video

"Agrega estos videos de YouTube a la carpeta 'Training': [URL video1], [URL video2]."

Claude usara sutram_get_folder para encontrar la carpeta "Training", luego llamara a sutram_create_video_link por cada URL. Sutram detecta que son videos de YouTube y extrae las miniaturas automaticamente.

Descargar un archivo

"Dame el enlace de descarga del archivo 'site-plan.pdf'."

Claude usara sutram_get_folder para encontrar el archivo, luego sutram_get_item para obtener una URL de descarga presignada. La URL es temporal y se puede usar para descargar el archivo directamente.

Etiquetar y buscar carpetas

"Organiza mis examenes medicos por paciente y tipo de examen, luego encuentra todas las carpetas del paciente João."

Claude:

Usara sutram_create_folder con path y tags para crear carpetas estructuradas con metadata
Usara sutram_set_folder_tags para agregar o actualizar tags en carpetas existentes
Usara sutram_search_folders con tag_name: "patient" y tag_value: "João" para encontrar todas las carpetas que coincidan (coincidencia de subcadena — tambien encuentra "João Pedro", "João Silva")

Los tags permiten que los asistentes de IA creen estructuras organizacionales ricas y buscables sin depender unicamente de los nombres de carpetas.

Descubrir tags y realizar busquedas AND

"Encuentra todos los examenes USG del paciente João dentro de la carpeta del Dr. Mion."

Claude:

Usara sutram_get_tag_keys con el ID de la carpeta para descubrir las claves de tags disponibles en ese ambito

Usara sutram_search_folders con multiples condiciones AND:

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

Devolvera solo las carpetas que coincidan con ambas condiciones dentro de la jerarquia especificada

Subir archivos via script

Al subir archivos a traves de un asistente de IA, el asistente usa el flujo de URL presignada en dos pasos: sutram_request_upload para obtener una URL presignada de S3 PUT, luego sube el archivo directamente a S3, y finalmente llama a sutram_confirm_upload para crear el registro del archivo. Este enfoque evita la sobrecarga de codificacion base64 y no tiene un limite practico de tamano de archivo mas alla de la cuota de almacenamiento de tu plan.

Para automatizacion o subidas en lote fuera del contexto del asistente de IA, puedes llamar al endpoint MCP directamente via HTTP.

Como funciona el endpoint HTTP de MCP

El servidor MCP de Sutram usa el transporte Streamable HTTP (JSON-RPC 2.0 sobre HTTPS):

Inicializar una sesion — POST https://app.sutram.io/mcp con metodo initialize
Capturar el ID de sesion — del header de respuesta mcp-session-id
Enviar una notificacion — notifications/initialized (requerido por el protocolo MCP)
Llamar herramientas — POST con metodo tools/call, pasando el nombre de la herramienta y los argumentos

Todas las solicitudes deben incluir los headers de autenticacion (x-project-key y x-user-key) y, despues de la inicializacion, el header mcp-session-id.

Ejemplo: Script de subida en Node.js

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();

Guarda como upload.mjs y ejecuta:

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

Integracion con skills de Claude Code

Si usas Claude Code, puedes envolver este script como un skill para que el asistente pueda invocarlo automaticamente cuando necesite subir archivos. Coloca el script en .claude/skills/sutram-upload/scripts/upload.mjs y crea un SKILL.md que instruya a Claude sobre como llamarlo. De esta manera, cuando el asistente encuentre un archivo para subir, delega la E/S pesada al script externo mientras mantiene la orquestacion en la conversacion.

Puntos clave

Sin limite de tamano de archivo mas alla de la cuota de almacenamiento de tu plan de Sutram
Los archivos se suben directamente a S3 via URL presignada — sin codificacion base64, sin datos a traves del servidor web
El script maneja el handshake MCP completo (initialize -> notify -> tool call)
La respuesta puede llegar como JSON o Server-Sent Events (SSE) dependiendo del tiempo de procesamiento — el script maneja ambos
Las credenciales se pueden leer desde .mcp.json para evitar dejarlas hardcodeadas

REST API

Ademas de las herramientas MCP, Sutram proporciona una REST API para consumo de solo lectura del contenido del proyecto. Usa la misma autenticacion de doble clave y es ideal para aplicaciones externas, dashboards y scripts.

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

Endpoints:

Endpoint	Descripcion
`GET /api/v1/project`	Informacion del proyecto
`GET /api/v1/folders`	Listar carpetas raiz
`GET /api/v1/folders/:id`	Detalle de carpeta con subcarpetas y elementos
`GET /api/v1/content`	Listar elementos de contenido con filtrado, busqueda por tags y paginacion
`GET /api/v1/content/:id`	Detalle de elemento de contenido con URLs de descarga presignadas

Documentacion completa: REST API v1 Reference