Guia do Sutram MCP Server

Versão: 0.111.0 Data: 2026-03-14 Status: Em desenvolvimento

Visão Geral

O Acesso Remoto do Sutram permite que assistentes de IA e ferramentas de automação se conectem aos seus projetos através do Model Context Protocol (MCP). Uma vez configurado, seu assistente de IA pode navegar por pastas, fazer upload de arquivos, adicionar links web/vídeo/áudio, gerenciar conteúdo e interagir com comentários de documentos nos seus projetos Sutram — tudo com autenticação e permissões adequadas.

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)

Duas chaves de API são necessárias para cada conexão:

Chave	Finalidade	Quem cria	Onde encontrar
Chave do Projeto (`sk_proj_...`)	Identifica o projeto	Proprietário do projeto	Página do projeto ou configurações do projeto
Chave do Usuário (`sk_user_...`)	Identifica você	Cada usuário cria a sua própria	Configurações do Usuário > API Key

Ambas as chaves devem ser válidas e você deve ser um membro ativo do projeto (não um visualizador) para se conectar.

Primeiros Passos

Passo 1: Crie sua chave de API pessoal

Vá em Settings (ícone de engrenagem no menu superior direito)
Clique no card API Key
Clique em Create Key
Copie a chave imediatamente — ela será exibida apenas uma vez

Sua chave pessoal se parece com: sk_user_zQD0BjH56nQhOgX3uxni...

Importante: Armazene sua chave de forma segura. Se você perdê-la, pode revogar a antiga e criar uma nova chave na mesma página de configurações.

Passo 2: Obtenha a chave do projeto

O proprietário do projeto deve primeiro habilitar o acesso remoto para o projeto:

Vá em Settings > aba Projects
Abra o menu suspenso (três pontos) ao lado do projeto
Clique em Enable Remote Access
Copie a chave do projeto que aparece

Uma vez que o acesso remoto esteja habilitado, qualquer membro do projeto (proprietário, administrador ou membro) pode copiar a chave do projeto:

Abra o projeto
Clique no ícone de sinal verde ao lado do selo de função no cabeçalho
Um modal exibirá a chave do projeto — clique no botão de copiar

A chave do projeto se parece com: sk_proj_ej8NWMisd2rJgMwAJ22T...

Configurando Seu Cliente de IA

Cada projeto Sutram deve ter sua própria configuração MCP local. Como a chave do projeto está vinculada a um projeto específico, a abordagem recomendada é criar uma pasta de workspace dedicada para cada integração e colocar o arquivo .mcp.json lá.

Exemplo: Se você usa o Sutram para armazenar exames médicos, crie uma pasta local para esse fluxo de trabalho:

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

Isso mantém as credenciais no contexto correto e evita misturar projetos não relacionados.

Claude Code (CLI) — Recomendado

Crie um arquivo .mcp.json na sua pasta de workspace:

{
  "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 ainda não suporta type: "url" nativamente. A configuração acima usa mcp-remote como ponte para conectar via stdio. Isso requer que o Node.js (npx) esteja instalado. O pacote mcp-remote é baixado automaticamente no primeiro uso.

Em seguida, inicie o Claude Code a partir dessa pasta. As ferramentas do Sutram estarão disponíveis apenas nesse contexto.

Cursor

Crie um arquivo .cursor/mcp.json na sua pasta de workspace:

{
  "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 um arquivo de configuração global. Adicione uma entrada para cada projeto Sutram, usando um nome descritivo para distingui-los:

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

Se a sua versão do Claude Desktop suporta 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"
      }
    }
  }
}

Se type: "url" não for reconhecido, use a ponte mcp-remote:

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

Reinicie o Claude Desktop após salvar o arquivo.

Dica: A chave de usuário (sk_user_...) é a mesma em todas as entradas — ela identifica você. A chave do projeto (sk_proj_...) muda por projeto.

Outros Clientes MCP

O Sutram usa o transporte MCP Streamable HTTP. Qualquer cliente compatível com MCP que suporte transporte HTTP pode se conectar usando:

Endpoint: https://app.sutram.io/mcp
Método: POST (JSON-RPC 2.0)
Autenticação: Headers personalizados x-project-key e x-user-key
Versão do protocolo: 2024-11-05

Para clientes que suportam apenas transporte stdio, use mcp-remote como ponte:

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"

Ferramentas Disponíveis

Uma vez conectado, seu assistente de IA tem acesso a estas ferramentas. Você também pode obter esta lista programaticamente enviando a requisição MCP padrão tools/list para o endpoint do servidor.

Referência Rápida (A–Z)

#	Ferramenta	Categoria	Descrição
1	`sutram_add_enum_values`	Schema	Adiciona novos valores a uma definição de metadados enum existente
2	`sutram_cancel_checkout`	Versionamento	Cancela o checkout sem fazer upload de alterações
3	`sutram_checkin_file`	Versionamento	Libera um arquivo do checkout (checkin)
4	`sutram_checkout_file`	Versionamento	Faz checkout de um arquivo para edição exclusiva
5	`sutram_confirm_upload`	Conteúdo	Passo 2 do upload: confirma que o arquivo foi enviado ao S3
6	`sutram_bulk_create_file_links`	File Links	Cria file links em massa de uma pasta de origem para uma pasta de destino
7	`sutram_cancel_checkout`	Versionamento	Cancela o checkout sem fazer upload de alterações
8	`sutram_checkin_file`	Versionamento	Libera um arquivo do checkout (checkin)
9	`sutram_checkout_file`	Versionamento	Faz checkout de um arquivo para edição exclusiva
10	`sutram_confirm_upload`	Conteúdo	Passo 2 do upload: confirma que o arquivo foi enviado ao S3
11	`sutram_create_audio_link`	Conteúdo	Cria um link de áudio (Spotify, SoundCloud, etc.)
12	`sutram_create_comment`	Comentários	Cria um comentário no nível do arquivo ou em markdown em um item de conteúdo
13	`sutram_create_file_link`	File Links	Cria um file link (referência simbólica) para um arquivo existente
14	`sutram_create_folder`	Pastas	Cria uma nova pasta ou caminho aninhado
15	`sutram_create_new_version`	Versionamento	Cria uma nova versão a partir de um arquivo publicado
16	`sutram_create_record`	Registros	Cria um novo registro em uma categoria
17	`sutram_create_video_link`	Conteúdo	Cria um link de vídeo (YouTube, Vimeo, etc.)
18	`sutram_create_web_link`	Conteúdo	Cria um link web com título obtido automaticamente
19	`sutram_delete`	Conteúdo	Exclui um item de conteúdo ou pasta
20	`sutram_delete_comment`	Comentários	Exclui um comentário e todas as suas respostas
21	`sutram_delete_metadata`	Schema	Exclui uma definição de metadados
22	`sutram_delete_record`	Registros	Exclui um registro
23	`sutram_delete_record_category`	Schema	Exclui uma categoria de registros
24	`sutram_disable_versioning`	Versionamento	Converte o arquivo de volta para referência (somente leitura)
25	`sutram_enable_versioning`	Versionamento	Converte o arquivo de referência para editável
26	`sutram_force_release_lock`	Versionamento	Libera forçadamente o checkout de outro usuário (apenas proprietário)
27	`sutram_get_comment_thread`	Comentários	Obtém um comentário com sua thread completa de respostas
28	`sutram_get_folder`	Pastas	Retorna o conteúdo de uma pasta
29	`sutram_get_item`	Conteúdo	Obtém detalhes completos e URL de download de um item de conteúdo
30	`sutram_get_item_tag_keys`	Tags	Retorna todas as chaves de tag distintas usadas em itens de conteúdo
31	`sutram_get_metadata_definitions`	Schema	Retorna todas as definições de campos de metadados
32	`sutram_get_record_categories`	Schema	Retorna todas as categorias de registros
33	`sutram_get_record_category_detail`	Schema	Retorna uma categoria com metadados completamente resolvidos
34	`sutram_get_tag_keys`	Tags	Retorna todas as chaves de tag distintas usadas em pastas
35	`sutram_list_comments`	Comentários	Lista todos os comentários de nível superior em um item de conteúdo
36	`sutram_list_file_links_for_source`	File Links	Lista todos os file links que apontam para um arquivo de origem
37	`sutram_list_file_links_in_folder`	File Links	Lista file links em uma pasta com detalhes do arquivo de origem
38	`sutram_list_versions`	Versionamento	Lista todas as versões de um arquivo
39	`sutram_move_contents`	Pastas	Move todo o conteúdo de uma pasta para outra
40	`sutram_move_item`	Conteúdo	Move um único item de conteúdo para outra pasta
41	`sutram_project_info`	Projeto	Retorna nome, descrição e configurações do projeto
42	`sutram_publish_version`	Versionamento	Publica um arquivo rascunho, criando um snapshot de versão
43	`sutram_remove_enum_values`	Schema	Remove valores de uma definição de metadados enum
44	`sutram_rename`	Conteúdo	Renomeia um item de conteúdo ou pasta
45	`sutram_reply_to_comment`	Comentários	Responde a um comentário de nível superior existente
46	`sutram_request_upload`	Conteúdo	Passo 1 do upload: retorna uma URL S3 PUT pré-assinada
47	`sutram_resolve_comment`	Comentários	Resolve ou reabre uma thread de comentário
48	`sutram_search_folders`	Tags	Busca pastas por tag (condição única ou condições AND)
49	`sutram_search_items`	Tags	Busca itens de conteúdo por tag
50	`sutram_set_folder_tags`	Tags	Define tags chave-valor em uma pasta
51	`sutram_set_item_tags`	Tags	Define tags chave-valor em um item de conteúdo
52	`sutram_undo_checkin`	Versionamento	Desfaz o último checkin, restaurando a versão anterior
53	`sutram_update_record`	Registros	Atualiza os metadados de um registro
54	`sutram_upload_modified_file`	Versionamento	Substitui o conteúdo do arquivo durante o checkout
55	`sutram_upsert_metadata`	Schema	Cria ou atualiza uma definição de campo de metadados
56	`sutram_upsert_record_category`	Schema	Cria ou atualiza uma categoria de registros

Categorias: Projeto (1) · Pastas (3) · Conteúdo (8) · File Links (4) · Tags (6) · Versionamento (12) · Comentários (6) · Schema (8) · Registros (4)

As seções abaixo descrevem cada ferramenta em detalhe, organizadas por funcionalidade.

sutram_project_info

Retorna informações sobre o projeto atual.

Parâmetros: Nenhum

Exemplo de resposta:

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

sutram_get_folder

Navega pelo conteúdo de uma pasta (subpastas, arquivos e links). Omita folder_id para listar o conteúdo da raiz.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`folder_id`	string	Não	UUID da pasta. Omita para a raiz.

Exemplo de resposta:

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

Cria uma nova pasta. Suporta a criação de hierarquias aninhadas em uma única chamada.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Sim*	Nome da pasta (para criar uma única pasta)
`path`	string	Sim*	Caminho separado por barras para criação aninhada (ex.: `"A/B/C"`)
`parent_folder_id`	string	Não	UUID da pasta pai. Omita para o nível raiz.
`tags`	object	Não	Tags chave-valor de formato livre (ex.: `{"patient": "John", "exam_type": "USG"}`). Ao usar `path`, as tags são aplicadas apenas à pasta folha (mais profunda).

*Use name (pasta única) ou path (hierarquia aninhada), não ambos.

Criação aninhada: Ao usar path, pastas intermediárias são criadas automaticamente. Se qualquer pasta no caminho já existir, ela é reutilizada — a operação é idempotente.

Exemplo — pasta única:

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

Exemplo — hierarquia aninhada com tags:

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

Isso cria três pastas em uma chamada e retorna a mais profunda (2024-12-12) com as tags especificadas.

sutram_request_upload

Passo 1 do fluxo de upload direto. Valida o arquivo e retorna uma URL S3 PUT pré-assinada. O arquivo é enviado diretamente ao S3 pelo cliente — nenhum dado passa pelos servidores web do Sutram.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`filename`	string	Sim	Nome do arquivo com extensão (ex.: `report.pdf`)
`file_size`	integer	Sim	Tamanho do arquivo em bytes
`content_type`	string	Não	Tipo MIME. Detectado automaticamente pela extensão se omitido.
`folder_id`	string	Não	UUID da pasta de destino. Omita para a raiz.

Exemplo de resposta:

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

Passo 2 do fluxo de upload direto. Chame após o arquivo ter sido enviado para a URL pré-assinada. Verifica se o objeto S3 existe, cria o registro do arquivo, atualiza o uso de armazenamento e enfileira compressão se aplicável.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`file_id`	string	Sim	UUID do arquivo de `sutram_request_upload`
`s3_key`	string	Sim	Chave S3 de `sutram_request_upload`
`filename`	string	Sim	Nome original do arquivo com extensão
`content_type`	string	Sim	Tipo MIME do arquivo
`file_size`	integer	Sim	Tamanho do arquivo em bytes
`folder_id`	string	Não	UUID da pasta de destino (deve corresponder à requisição)

Exemplo de resposta:

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

Exemplo completo do fluxo de upload:

# 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

Cria um link web no projeto. O Sutram busca automaticamente o título da página e o favicon a partir da URL.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL da página web (deve ser http ou https)
`name`	string	Não	Nome de exibição. Obtido automaticamente do título da página se omitido.
`folder_id`	string	Não	UUID da pasta de destino. Omita para a raiz.

Exemplo de resposta:

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

Cria um link de vídeo no projeto. Suporta YouTube, Vimeo, DailyMotion, Wistia, Loom e TikTok. Detecta automaticamente a plataforma e extrai o ID do vídeo a partir da URL.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL do vídeo (ex.: `https://www.youtube.com/watch?v=...`)
`name`	string	Não	Nome de exibição. Usa a URL como padrão se omitido.
`folder_id`	string	Não	UUID da pasta de destino. Omita para a raiz.

Exemplo de resposta:

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

Cria um link de áudio no projeto. Suporta Spotify, SoundCloud, Apple Podcasts e outros. Detecta automaticamente a plataforma e extrai o ID do áudio a partir da URL.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL do conteúdo de áudio (ex.: `https://open.spotify.com/track/...`)
`name`	string	Não	Nome de exibição. Usa a URL como padrão se omitido.
`folder_id`	string	Não	UUID da pasta de destino. Omita para a raiz.

Exemplo de resposta:

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

Cria um file link (referência simbólica) para um arquivo existente no projeto. O link aparece como uma referência somente leitura sem duplicar armazenamento ou versionamento. A origem deve ser um arquivo (não um link ou outro file link). Se o arquivo de origem for excluído, todos os seus file links são removidos automaticamente.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`source_content_item_id`	string	Sim	UUID do item de conteúdo do arquivo de origem para vincular
`name`	string	Não	Nome de exibição (usa o nome do arquivo de origem como padrão)
`folder_id`	string	Não	UUID da pasta de destino (omita para a raiz)
`description`	string	Não	Descrição do file link

Exemplo de requisição:

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

Exemplo de resposta:

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

Cria file links em massa para todos os arquivos (ou um subconjunto filtrado) em uma pasta de origem, colocando-os em uma pasta de destino. Pula automaticamente arquivos que já possuem um link na pasta de destino (deduplicação). Ideal para fluxos de trabalho como vincular múltiplos arquivos de exames a uma pasta centralizada de laudos.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`source_folder_id`	string	Sim	UUID da pasta de origem contendo os arquivos a vincular
`target_folder_id`	string	Sim	UUID da pasta de destino onde os file links serão criados
`name_pattern`	string	Não	Filtro de substring (case-insensitive) nos nomes dos arquivos de origem. Apenas arquivos correspondentes são vinculados.
`recursive`	boolean	Não	Incluir arquivos de subpastas da pasta de origem (padrão: false)

Exemplo de requisição:

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

Exemplo de resposta:

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

Dica: Executar o mesmo comando novamente pulará todos os arquivos previamente vinculados ("created": 0, "skipped": 7), tornando seguro re-executar.

sutram_list_file_links_for_source

Lista todos os file links que apontam para um determinado arquivo de origem. Responde à pergunta: "onde este arquivo é referenciado?" Retorna cada link com seu caminho de pasta.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`source_content_item_id`	string	Sim	UUID do item de conteúdo do arquivo de origem

Exemplo de requisição:

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

Exemplo de resposta:

{
  "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 os file links em uma pasta, enriquecidos com detalhes do arquivo de origem (nome, tipo de conteúdo, tamanho, caminho da pasta). Diferente de sutram_get_folder, este fornece informações completas sobre o arquivo de origem para o qual cada link aponta.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`folder_id`	string	Não	UUID da pasta (omita para a raiz)

Exemplo de requisição:

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

Exemplo de resposta:

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

Obtém detalhes completos de um item de conteúdo por ID. Para arquivos, retorna metadados e uma URL de download pré-assinada. Para links (web, vídeo, áudio, file_link), retorna a URL, informações da plataforma e metadados.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`content_item_id`	string	Sim	UUID do item de conteúdo

Exemplo de resposta (arquivo):

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

Exemplo de resposta (link 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"
}

Exemplo de resposta (link de vídeo):

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

Exclui um item de conteúdo (arquivo, link web, link de vídeo, link de áudio) ou pasta do projeto.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`item_id`	string	Sim	UUID do item de conteúdo ou pasta
`item_type`	string	Sim	`"content_item"` ou `"folder"`. Use `"content_item"` para qualquer tipo de conteúdo (arquivos, links web, links de vídeo, links de áudio).

sutram_rename

Renomeia um item de conteúdo (arquivo, link web, link de vídeo, link de áudio) ou pasta.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`item_id`	string	Sim	UUID do item de conteúdo ou pasta
`item_type`	string	Sim	`"content_item"` ou `"folder"`. Use `"content_item"` para qualquer tipo de conteúdo (arquivos, links web, links de vídeo, links de áudio).
`new_name`	string	Sim	Novo nome (para arquivos, inclua a extensão)

sutram_move_contents

Move todo o conteúdo (subpastas e arquivos) de uma pasta de origem para uma pasta de destino. A pasta de origem é esvaziada mas não excluída. Conflitos de nome são tratados automaticamente.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`source_folder_id`	string	Sim	UUID da pasta de origem a esvaziar
`target_folder_id`	string	Sim	UUID da pasta de destino para receber o conteúdo

Tratamento de conflitos de nome: Se uma subpasta ou arquivo com o mesmo nome já existir na pasta de destino, o Sutram renomeia automaticamente o item movido adicionando um sufixo numérico: Exams se torna Exams (1), report.pdf se torna report (1).pdf, e assim por diante.

Regras de validação:

Origem e destino devem ser pastas diferentes
O destino não pode ser uma subpasta da origem (previne movimentações circulares)
Ambas as pastas devem existir no projeto atual

Exemplo de resposta:

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

Move um único item de conteúdo (arquivo ou link) para outra pasta. Conflitos de nome são tratados automaticamente.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`content_item_id`	string	Sim	UUID do item de conteúdo a mover
`target_folder_id`	string/null	Não	UUID da pasta de destino (null para a raiz)

Tratamento de conflitos de nome: Se um arquivo com o mesmo nome já existir na pasta de destino, o Sutram renomeia automaticamente o arquivo movido adicionando um sufixo numérico: report.pdf se torna report (1).pdf, e assim por diante.

Exemplo de resposta (sem conflito):

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

Exemplo de resposta (com renomeação):

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

sutram_set_folder_tags

Define tags chave-valor de formato livre em uma pasta. Substitui todas as tags existentes. Envie {} para limpar todas as tags.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`folder_id`	string	Sim	UUID da pasta
`tags`	object	Sim	Tags chave-valor a definir. Envie `{}` para limpar todas as tags.

Limites: Máximo de 50 tags por pasta. Chave com máximo de 100 caracteres, valor com máximo de 500 caracteres.

Semântica: Esta é uma operação PUT — substitui todas as tags existentes. Para adicionar uma tag sem remover as outras, primeiro leia as tags atuais (via sutram_get_folder), mescle suas alterações e então chame sutram_set_folder_tags com o conjunto completo.

Exemplo — definir tags:

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

Exemplo — limpar todas as tags:

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

Exemplo de resposta:

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

sutram_search_folders

Busca pastas por tag. Suporta condição única ou múltiplas condições AND. Toda a correspondência é case-insensitive para chaves e valores. Valores suportam correspondência por substring (ex.: "orto" corresponde a "Ortopedia"). Use folder_id para restringir a busca aos descendentes de uma pasta específica.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`tag_name`	string	Não*	Chave da tag a buscar (modo de condição única). Case-insensitive.
`tag_value`	string	Não	Valor a corresponder (modo de condição única). Correspondência por substring, case-insensitive.
`conditions`	array	Não*	Múltiplas condições AND. Cada objeto tem `key` (obrigatório) e `value` (opcional).
`folder_id`	string	Não	UUID da pasta para delimitar a busca. Busca apenas descendentes desta pasta.

*Use tag_name (condição única) ou conditions (múltiplas condições AND).

Comportamento da busca:

Correspondência de chave: Correspondência exata case-insensitive ("Patient" corresponde a "patient")
Correspondência de valor: Correspondência por substring case-insensitive ("orto" corresponde a "Ortopedia", "joão" corresponde a "João Silva")
Sem valor: Quando o valor é omitido, corresponde a qualquer pasta que tenha a chave independentemente do valor
Múltiplas condições: Todas as condições devem corresponder (lógica AND)

Exemplo — encontrar todas as pastas com tag "patient":

{ "tag_name": "patient" }

Exemplo — encontrar pastas para um paciente específico (correspondência por substring):

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

Isso corresponde a pastas onde a tag "patient" contém "joão" (ex.: "João Silva", "João Pedro").

Exemplo — busca AND com múltiplas condições:

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

Isso retorna apenas pastas que correspondem a ambas as condições.

Exemplo — buscar apenas dentro de uma hierarquia de pastas específica:

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

Exemplo de resposta:

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

Retorna todas as chaves de tag distintas usadas em pastas no projeto. Útil para descobrir quais tags estão disponíveis antes de realizar uma busca. Use folder_id para restringir aos descendentes de uma pasta específica.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`folder_id`	string	Não	UUID da pasta para delimitar. Retorna apenas chaves de descendentes desta pasta.

Exemplo — obter todas as chaves de tag no projeto:

{}

Exemplo — obter chaves de tag dentro de uma hierarquia de pastas:

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

Exemplo de resposta:

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

sutram_set_item_tags

Define tags chave-valor de formato livre em um item de conteúdo. Substitui todas as tags existentes. Envie {} para limpar todas as tags.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`content_item_id`	string	Sim	UUID do item de conteúdo
`tags`	object	Sim	Tags chave-valor a definir. Envie `{}` para limpar todas as tags.

Limites: Máximo de 50 tags por item. Chave com máximo de 100 caracteres, valor com máximo de 500 caracteres.

Semântica: Esta é uma operação PUT — substitui todas as tags existentes. Para adicionar uma tag sem remover as outras, primeiro leia as tags atuais (via sutram_get_item), mescle suas alterações e então chame sutram_set_item_tags com o conjunto completo.

Exemplo — definir tags:

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

Exemplo — limpar todas as tags:

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

Exemplo de resposta:

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

sutram_search_items

Busca itens de conteúdo por tag. Suporta condição única ou múltiplas condições AND. Toda a correspondência é case-insensitive para chaves e valores. Valores suportam correspondência por substring (ex.: "neuro" corresponde a "Neurologia"). Use folder_id para restringir a busca a uma pasta específica, e type para filtrar por tipo de conteúdo.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`tag_name`	string	Não*	Chave da tag a buscar (modo de condição única). Case-insensitive.
`tag_value`	string	Não	Valor a corresponder (modo de condição única). Correspondência por substring, case-insensitive.
`conditions`	array	Não*	Múltiplas condições AND. Cada objeto tem `key` (obrigatório) e `value` (opcional).
`folder_id`	string	Não	UUID da pasta para delimitar a busca.
`type`	string	Não	Filtro de tipo de conteúdo: `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

*Use tag_name (condição única) ou conditions (múltiplas condições AND).

Exemplo — encontrar todos os itens com tag "topic":

{ "tag_name": "topic" }

Exemplo — encontrar itens para um tópico específico (correspondência por substring):

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

Exemplo — busca AND com múltiplas condições:

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

Exemplo — buscar apenas links de vídeo em uma pasta específica:

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

Exemplo de resposta:

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

sutram_get_item_tag_keys

Retorna todas as chaves de tag distintas usadas em itens de conteúdo no projeto. Útil para descobrir quais tags estão disponíveis antes de realizar uma busca. Use folder_id para restringir a uma pasta específica, e type para filtrar por tipo de conteúdo.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`folder_id`	string	Não	UUID da pasta para delimitar.
`type`	string	Não	Filtro de tipo de conteúdo: `"file"`, `"file_link"`, `"web_link"`, `"video_link"`, `"audio_link"`

Exemplo — obter todas as chaves de tag de conteúdo no projeto:

{}

Exemplo — obter chaves de tag apenas para links de vídeo:

{ "type": "video_link" }

Exemplo de resposta:

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

Versionamento de Arquivos

O Sutram suporta um fluxo completo de versionamento para arquivos via MCP. Isso permite que assistentes de IA habilitem controle de versão, façam checkout de arquivos para edição exclusiva, façam upload de modificações e publiquem versões.

Fluxo de Trabalho

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)

Ferramentas de Versionamento

Ferramenta	Descrição	Permissão
`sutram_enable_versioning`	Converte arquivo de referência para editável (inicia versionamento)	Proprietário, Membro
`sutram_disable_versioning`	Converte arquivo de volta para referência (para versionamento)	Proprietário, Membro
`sutram_checkout_file`	Faz checkout do arquivo para edição exclusiva	Proprietário, Admin, Membro
`sutram_checkin_file`	Libera o bloqueio de checkout	Usuário do checkout
`sutram_cancel_checkout`	Cancela o checkout sem alterações	Usuário do checkout
`sutram_force_release_lock`	Libera forçadamente o checkout de outro usuário	Apenas proprietário
`sutram_publish_version`	Publica um arquivo rascunho, criando um snapshot de versão	Apenas proprietário
`sutram_create_new_version`	Inicia nova versão a partir de arquivo publicado	Apenas proprietário
`sutram_undo_checkin`	Desfaz o último checkin, restaura a versão anterior	Usuário do último checkin
`sutram_list_versions`	Lista todas as versões publicadas com URLs de download	Qualquer membro
`sutram_upload_modified_file`	Substitui o conteúdo do arquivo durante o checkout	Usuário do checkout

Parâmetros

Todas as ferramentas de versionamento requerem content_item_id (UUID do item de conteúdo).

sutram_upload_modified_file adicionalmente requer:

Parâmetro	Tipo	Descrição
`s3_key`	string	Chave S3 de `sutram_request_upload`
`file_name`	string	Nome do arquivo com extensão
`file_size`	integer	Tamanho do arquivo em bytes
`content_type`	string	Tipo MIME

Exemplo: Fluxo Completo de Versionamento

// 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 e Registros

O Sutram suporta registros estruturados com schemas de metadados e slugs gerados automaticamente. Isso permite que assistentes de IA definam campos de metadados, criem categorias de registros e gerenciem registros programaticamente.

Requisito de plano: As ferramentas de gerenciamento de registros e schema requerem um plano com o recurso Records habilitado (Plus ou superior). As ferramentas somente leitura (sutram_get_metadata_definitions, sutram_get_record_categories, sutram_get_record_category_detail) estão disponíveis em todos os planos.

Conceitos

Definições de metadados — Schemas de campo que definem os tipos, rótulos e valores permitidos para campos de metadados (ex.: "language" como enum com valores "PT", "EN", "ES").
Categorias de registros — Templates que definem quais campos de metadados um registro usa, sua ordem, como a base numérica é calculada (computed_from) e como o slug (nome do registro) é composto (slug_from).
Registros — Pastas criadas com uma categoria, metadados validados e um slug gerado automaticamente.

Geração de Slug

Registros possuem um slug gerado automaticamente (usado como nome do registro). O slug é construído em duas etapas:

Base numérica — Determinada pelas entradas computed_from em uma tag de metadados computada. Isso define quais valores de campo formam a chave de unicidade para numeração sequencial.
Composição do slug — Determinada pelas entradas slug_from na categoria. Isso define quais valores de campo (incluindo a tag computada) compõem o slug final.

Sem slug_from (compatível com versões anteriores): slug = number_base + separator + sequence_number (ex.: 0100-200-001).

Com slug_from: slug é composto a partir dos campos referenciados em ordem (ex.: MD-3010.95-0000-000-SWA-001).

Ferramentas de Schema

Ferramenta	Descrição	Permissão
`sutram_get_metadata_definitions`	Lista todas as definições de metadados	Qualquer membro
`sutram_get_record_categories`	Lista todas as categorias de registros	Qualquer membro
`sutram_get_record_category_detail`	Categoria com metadados resolvidos (rótulos, tipos, valores permitidos)	Qualquer membro
`sutram_upsert_metadata`	Cria ou atualiza uma definição de metadados	Apenas proprietário
`sutram_delete_metadata`	Exclui uma definição de metadados (falha se estiver em uso)	Apenas proprietário
`sutram_add_enum_values`	Adiciona valores a uma definição enum (mescla, deduplica, ordena)	Apenas proprietário
`sutram_remove_enum_values`	Remove valores de uma definição enum por código	Apenas proprietário
`sutram_upsert_record_category`	Cria ou atualiza uma categoria de registros	Apenas proprietário
`sutram_delete_record_category`	Exclui uma categoria de registros	Apenas proprietário

Ferramentas CRUD de Registros

Ferramenta	Descrição	Permissão
`sutram_create_record`	Cria um registro com categoria, metadados e slug gerado automaticamente	Proprietário, Admin, Membro
`sutram_update_record`	Atualiza os metadados de um registro (recalcula o slug se necessário)	Proprietário, Admin, Membro
`sutram_delete_record`	Exclui um registro e todo seu conteúdo recursivamente	Proprietário, Admin, Membro

sutram_get_metadata_definitions

Retorna todas as definições de metadados do projeto. Cada definição possui uma chave e propriedades: rótulo, tipo (text, enum, boolean, date, computed) e opcionalmente values, depends_on, values_map.

Parâmetros: Nenhum

sutram_get_record_categories

Retorna todas as categorias de registros do projeto. Cada categoria define quais campos de metadados um registro usa, configuração de slug e ordenação.

Parâmetros: Nenhum

sutram_get_record_category_detail

Retorna uma categoria de registros com metadados completamente resolvidos (rótulos, tipos, valores permitidos a partir das definições). Use isso para entender quais campos são necessários antes de criar um registro.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	ID da categoria de registros

sutram_upsert_metadata

Cria ou atualiza uma definição de metadados (schema de campo). Para tipos enum, forneça o array completo de values. Para enums grandes, prefira sutram_add_enum_values para adições incrementais.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave única (snake_case, ex.: `"specialty"`)
`definition`	object	Sim	Definição com `label`, `type` e campos opcionais

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

Exemplo — criar um enum simples:

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

sutram_delete_metadata

Exclui uma definição de metadados. Falha se a definição estiver atualmente em uso por alguma categoria de registros.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave da definição a excluir

sutram_add_enum_values

Adiciona valores a uma definição de metadados enum existente. Novos valores são mesclados com os existentes — duplicatas (por código) são ignoradas. Os valores são ordenados por código após a mesclagem. Use isso em vez de sutram_upsert_metadata ao trabalhar com enums grandes para evitar enviar o array inteiro de valores.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave da definição enum
`values`	array	Sim	Array de objetos `{label, code}` a adicionar

Exemplo — adicionar valores a um enum existente com mais de 800 itens:

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

Exemplo de resposta:

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

sutram_remove_enum_values

Remove valores de uma definição de metadados enum existente pelos seus códigos.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave da definição enum
`codes`	array	Sim	Array de strings de código a remover

Exemplo:

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

Exemplo de resposta:

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

sutram_upsert_record_category

Cria ou atualiza uma categoria de registros. Os metadados devem referenciar definições existentes. Use computed_from em uma entrada de metadados para definir a base numérica (unicidade). Use slug_from no nível da categoria para definir como o slug (nome do registro) é composto.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	ID único da categoria (snake_case)
`category`	object	Sim	Definição da categoria (veja campos abaixo)

Campos da categoria:

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome de exibição da categoria
`metadata`	array	Sim	Array de referências a campos de metadados (veja abaixo)
`slug_separator`	string	Não	Separador entre partes do slug (padrão: `"-"`)
`slug_from`	array	Não	Define a composição do slug. Cada entrada tem `key` e `use` (`"code"` ou `"label"`). Se omitido, slug = number_base + separator + sequence_number

Campos de entrada de metadados:

Campo	Tipo	Obrigatório	Descrição
`key`	string	Sim	Chave de uma definição de metadados existente
`required`	boolean	Não	Se este campo é obrigatório (padrão: false)
`order`	integer	Não	Ordem de exibição (base 0)
`computed_from`	array	Não	Apenas para tags computadas. Define a base numérica. Cada entrada tem `key` e `use` (`"code"` ou `"label"`)
`sequence_digits`	integer	Não	Apenas para tags computadas. Dígitos para o número sequencial (2-4, padrão: 2)

Exemplo — categoria com 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" }
    ]
  }
}

Neste exemplo:

Base numérica (de computed_from): MD-3010.95-0000-000 — determina a unicidade sequencial
Número codificado: 001 (próxima sequência disponível)
Slug (de slug_from): MD-3010.95-0000-000-SWA-001 — inclui document_origin + sequência

Exemplo — categoria simples sem slug_from (compatível com versões 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": "-"
  }
}

Sem slug_from, o slug é automaticamente: {number_base}{separator}{sequence} (ex.: CARDIO-001).

sutram_delete_record_category

Exclui uma categoria de registros.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	ID da categoria a excluir

sutram_create_record

Cria um registro com uma categoria, metadados validados e slug gerado automaticamente. O slug é calculado a partir da definição slug_from da categoria, ou de computed_from (base numérica) + separador + número sequencial. Use sutram_get_record_category_detail primeiro para ver os campos obrigatórios.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`category_id`	string	Sim	ID da categoria de registros
`metadata`	object	Sim	Pares chave-valor correspondentes aos campos de metadados da categoria
`parent_folder_id`	string	Não	UUID da pasta pai (omita para a raiz)
`name`	string	Não	Nome personalizado (usa o slug gerado automaticamente como padrão)

Exemplo:

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

A resposta inclui o slug calculado e o número sequencial:

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

Atualiza os metadados de um registro. Recalcula a base numérica e o slug quando campos de metadados referenciados por computed_from ou slug_from são alterados.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`record_id`	string	Sim	UUID do registro (pasta)
`metadata`	object	Sim	Pares chave-valor atualizados
`name`	string	Não	Novo nome (opcional)

sutram_delete_record

Exclui um registro e todo o seu conteúdo (subpastas e arquivos) recursivamente. Esta ação não pode ser desfeita.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`record_id`	string	Sim	UUID do registro (pasta) a excluir

Exemplo: Fluxo 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", ... } }

Observe como:

A base numérica PT-0100 (de computed_from: language + area) determina a unicidade sequencial
O slug PT-0100-SWA-001 (de slug_from) inclui origin + o número sequencial
O segundo registro recebe a sequência 002 porque compartilha a mesma base numérica PT-0100

Comentários em Documentos

Assistentes de IA podem listar, criar, responder, resolver e excluir comentários em arquivos do projeto. Comentários criados via MCP aparecem em tempo real na interface web e vice-versa, graças à transmissão PubSub.

Restrição de tipo de posição: Via MCP, a IA pode criar apenas comentários file_level (comentário no arquivo inteiro) ou markdown (ancorado a texto em arquivos markdown). Tipos de posição que requerem coordenadas da GUI (pdf_page, aps_3d, aps_2d, image) podem ser lidos mas não criados via MCP.

Ferramentas de Comentários

Ferramenta	Descrição	Permissão
`sutram_list_comments`	Lista todos os comentários de nível superior em um item de conteúdo	Qualquer membro
`sutram_get_comment_thread`	Obtém um comentário com sua thread completa de respostas	Qualquer membro
`sutram_create_comment`	Cria um comentário no nível do arquivo ou em markdown	Qualquer membro
`sutram_reply_to_comment`	Responde a um comentário de nível superior	Qualquer membro
`sutram_resolve_comment`	Resolve ou reabre uma thread de comentário	Qualquer membro
`sutram_delete_comment`	Exclui um comentário e todas as suas respostas	Autor, Proprietário ou Admin

sutram_list_comments

Lista todos os comentários de nível superior em um item de conteúdo. Retorna conteúdo do comentário, autor, tipo de posição, status de resolução e contagem de respostas.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`content_item_id`	string	Sim	UUID do item de conteúdo
`include_resolved`	boolean	Não	Se deve incluir comentários resolvidos (padrão: true)

Exemplo:

{
  "content_item_id": "abc-123"
}

Resposta:

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

Obtém um único comentário com sua thread completa de respostas, status de resolução e detalhes do autor.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`comment_id`	string	Sim	UUID do comentário

Resposta:

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

Cria um comentário em um item de conteúdo. A IA pode criar comentários file_level (padrão) ou markdown.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`content_item_id`	string	Sim	UUID do item de conteúdo
`content`	string	Sim	Texto do comentário
`position_type`	string	Não	`"file_level"` (padrão) ou `"markdown"`
`text_anchor`	object	Não	Para markdown: `{exact_text, prefix, suffix}`
`original_text_snippet`	string	Não	Para markdown: o trecho de texto selecionado

Exemplo — comentário no nível do arquivo:

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

Exemplo — comentário markdown ancorado 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 um comentário de nível superior existente. Respostas não podem ser aninhadas (sem resposta-de-resposta).

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`comment_id`	string	Sim	UUID do comentário de nível superior
`content`	string	Sim	Texto da resposta

Exemplo:

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

sutram_resolve_comment

Resolve ou reabre uma thread de comentário. Comentários resolvidos indicam que o problema foi tratado.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`comment_id`	string	Sim	UUID do comentário
`action`	string	Sim	`"resolve"` ou `"reopen"`

Exemplo:

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

sutram_delete_comment

Exclui um comentário e todas as suas respostas. Apenas o autor do comentário ou o proprietário/admin do projeto pode excluir.

Parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`comment_id`	string	Sim	UUID do comentário

Exemplo: Fluxo Completo de Comentários

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

Todas as alterações de comentários são transmitidas em tempo real para os usuários que estão visualizando o mesmo documento na interface web.

Limitações

As seguintes operações ainda não estão disponíveis via MCP e devem ser realizadas pela interface web do Sutram. Elas serão adicionadas em versões futuras:

Compartilhamento: Links de compartilhamento não podem ser gerados
Comentários posicionados: Criar comentários ancorados a páginas de PDF, coordenadas CAD ou posições em imagens requer a interface web

Permissões

Seu acesso MCP respeita as mesmas permissões da interface web:

Função	Navegar	Upload/Criar	Mover	Excluir	Versionamento	Schema de Registros	Registros	Comentários
Proprietário	Sim	Sim	Sim	Sim	Completo (publicar, liberar forçadamente)	Completo (CRUD de definições e categorias)	CRUD	Completo (listar, criar, responder, resolver, excluir qualquer)
Admin	Sim	Sim	Sim	Sim	Checkout/checkin	Somente leitura	CRUD	Completo (listar, criar, responder, resolver, excluir qualquer)
Membro	Sim	Sim	Sim	Sim	Habilitar/desabilitar, checkout/checkin	Somente leitura	CRUD	Listar, criar, responder, resolver, excluir próprios
Visualizador	Sem acesso MCP	—	—	—	—	—	—	—

Visualizadores não podem usar o acesso remoto. Se você precisa de acesso MCP, peça ao proprietário do projeto para atualizar sua função.

Segurança

Chaves são independentes: Revogar uma chave de usuário não afeta outros usuários. Revogar uma chave de projeto desabilita o acesso remoto para todos naquele projeto.
Uma chave de projeto por projeto: Apenas uma chave de projeto ativa existe por vez. Regenerá-la invalida a anterior.
Chaves nunca são armazenadas em texto puro: Chaves de projeto são criptografadas. Chaves de usuário são hasheadas — não podem ser recuperadas após a criação.
Rastreamento de atividade: Toda chave registra quando foi usada pela última vez.
Apenas HTTPS: Todas as conexões MCP usam HTTPS criptografado.

Revogando acesso

Para revogar sua chave pessoal:

Vá em Settings > API Key
Clique em "Revoke Key"
Crie uma nova se necessário

Para desabilitar o acesso remoto de um projeto (apenas proprietário):

Vá em Settings > Projects
Abra o menu suspenso do projeto
Clique em "Remote Access"
Clique em "Revoke Key"

Resolução de Problemas

"Authentication failed"

Verifique se ambas as chaves estão corretas e não foram revogadas
Certifique-se de que você é um membro ativo do projeto
Visualizadores não podem usar o acesso remoto — verifique sua função na página do projeto

"Project key not available"

A chave do projeto pode ter sido revogada pelo proprietário
Peça ao proprietário do projeto para regenerá-la nas configurações do projeto

"Storage quota exceeded"

O limite de armazenamento da sua conta foi atingido
Exclua arquivos não utilizados ou atualize seu plano

Ferramentas não aparecem no Claude Code

Claude Code ainda não suporta type: "url" — use a configuração de ponte mcp-remote (veja Configuração do Claude Code)
Certifique-se de que o Node.js está instalado (npx deve estar disponível no seu PATH)
Verifique se o arquivo .mcp.json está na pasta onde você inicia o Claude Code

Ferramentas não aparecem no Claude Desktop

Reinicie o Claude Desktop após editar o arquivo de configuração
Verifique se a sintaxe JSON é válida (sem vírgulas pendentes, aspas corretas)
Verifique se a URL do endpoint está correta
Se type: "url" não funcionar, tente a configuração de ponte mcp-remote (veja Configuração do Claude Desktop)

Timeout de conexão

Verifique sua conexão com a internet
Verifique se o serviço Sutram está acessível em https://sutram.io

Tipos de Arquivo Suportados

O Sutram detecta automaticamente tipos MIME a partir de extensões de arquivo. Formatos comuns suportados:

Categoria	Extensões
Imagens	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`
Documentos	`.pdf`, `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`
Texto	`.txt`, `.csv`, `.json`, `.xml`, `.md`
Mídia	`.mp4`, `.mp3`, `.wav`
Arquivos compactados	`.zip`
CAD	`.dwg`, `.dxf`, `.rvt`, `.ifc`

Arquivos com extensões não reconhecidas são enviados como application/octet-stream.

Plataformas de Links Suportadas

Plataformas de vídeo

YouTube, Vimeo, DailyMotion, Wistia, Loom e TikTok. A plataforma é detectada automaticamente a partir da URL, e miniaturas são extraídas quando disponíveis.

Plataformas de áudio

Spotify, SoundCloud, Apple Podcasts, Anchor e outros. A plataforma é detectada automaticamente a partir da URL.

Links web

Qualquer URL HTTP/HTTPS válida. Título da página, descrição e favicon são obtidos automaticamente.

Exemplos

Migrar exames médicos de portais hospitalares

"Baixe meu exame de ultrassom do portal do hospital e organize no Sutram na pasta do médico solicitante."

O assistente de IA irá:

Acessar o portal do hospital (via navegador)
Baixar o relatório em PDF e os arquivos de imagem
Usar sutram_create_folder para construir a estrutura de pastas em uma chamada: Nome do Médico / Tipo de Exame / AAAA-MM-DD
Usar sutram_request_upload + sutram_confirm_upload para fazer upload de cada arquivo diretamente ao S3
Limpar os arquivos temporários locais

Esse fluxo de trabalho garante que os dados médicos estejam devidamente organizados e nenhum arquivo sensível permaneça no computador local.

Fazer upload de um arquivo local

"Faça upload do arquivo report.pdf da minha área de trabalho para a pasta 'Reports' no Sutram."

Claude irá ler o arquivo, usar sutram_get_folder para encontrar a pasta "Reports", depois sutram_request_upload para obter uma URL pré-assinada, fazer upload do arquivo diretamente ao S3 via HTTP PUT e chamar sutram_confirm_upload para finalizar.

Organizar conteúdo do projeto

"Crie uma estrutura de pastas para nosso projeto de construção: Plans, Reports e Photos. Depois faça upload dessas fotos do canteiro."

Claude usará sutram_create_folder para cada pasta de nível superior, depois sutram_request_upload + sutram_confirm_upload para fazer upload de cada foto na pasta correta.

Limpar arquivos antigos

"Exclua todos os arquivos na pasta 'Temp'."

Claude usará sutram_get_folder para listar o conteúdo da pasta, depois sutram_delete para cada arquivo.

Reorganizar estrutura de pastas

"Mova todo o conteúdo da pasta '2024' para '2024-Archive' para liberar espaço na visualização principal."

Claude usará sutram_move_contents para transferir todas as subpastas e arquivos da origem para a pasta de destino em uma única operação. Se algum item tiver nome conflitante, será renomeado automaticamente com sufixos numéricos.

Mover um arquivo específico

"Mova o arquivo 'contract.pdf' para a pasta 'Legal'."

Claude usará sutram_get_folder para encontrar o arquivo e a pasta de destino, depois sutram_move_item para mover o arquivo. Se um arquivo com o mesmo nome já existir na pasta de destino, será renomeado automaticamente (ex.: contract (1).pdf).

Salvar um link web

"Salve este artigo no meu projeto: https://example.com/building-codes-2026"

Claude usará sutram_create_web_link com a URL. O Sutram busca automaticamente o título da página e o favicon, então o link aparece com seu nome correto no projeto.

Organizar referências de vídeo

"Adicione esses vídeos do YouTube à pasta 'Training': [URL do vídeo1], [URL do vídeo2]."

Claude usará sutram_get_folder para encontrar a pasta "Training", depois chamará sutram_create_video_link para cada URL. O Sutram detecta que são vídeos do YouTube e extrai miniaturas automaticamente.

Baixar um arquivo

"Me dê o link de download do arquivo 'site-plan.pdf'."

Claude usará sutram_get_folder para encontrar o arquivo, depois sutram_get_item para obter uma URL de download pré-assinada. A URL é temporária e pode ser usada para baixar o arquivo diretamente.

Etiquetar e buscar pastas

"Organize meus exames médicos por paciente e tipo de exame, depois encontre todas as pastas do paciente João."

Claude irá:

Usar sutram_create_folder com path e tags para criar pastas estruturadas com metadados
Usar sutram_set_folder_tags para adicionar ou atualizar tags em pastas existentes
Usar sutram_search_folders com tag_name: "patient" e tag_value: "João" para encontrar todas as pastas correspondentes (correspondência por substring — também encontra "João Pedro", "João Silva")

Tags permitem que assistentes de IA criem estruturas organizacionais ricas e pesquisáveis sem depender apenas de nomes de pastas.

Descobrir tags e realizar buscas AND

"Encontre todos os exames de USG do paciente João dentro da pasta do Dr. Mion."

Claude irá:

Usar sutram_get_tag_keys com o ID da pasta para descobrir as chaves de tag disponíveis naquele escopo

Usar sutram_search_folders com múltiplas condições AND:

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

Retornar apenas pastas que correspondam a ambas as condições dentro da hierarquia especificada

Fazendo Upload de Arquivos via Script

Ao fazer upload de arquivos por meio de um assistente de IA, o assistente usa o fluxo de URL pré-assinada em duas etapas: sutram_request_upload para obter uma URL S3 PUT pré-assinada, depois faz upload do arquivo diretamente ao S3 e finalmente chama sutram_confirm_upload para criar o registro do arquivo. Essa abordagem evita a sobrecarga de codificação base64 e não tem limite prático de tamanho de arquivo além da cota de armazenamento do seu plano.

Para automação ou uploads em lote fora do contexto do assistente de IA, você pode chamar o endpoint MCP diretamente via HTTP.

Como o endpoint HTTP MCP funciona

O servidor MCP do Sutram usa o transporte Streamable HTTP (JSON-RPC 2.0 sobre HTTPS):

Inicializar uma sessão — POST https://app.sutram.io/mcp com método initialize
Capturar o ID da sessão — do header de resposta mcp-session-id
Enviar uma notificação — notifications/initialized (exigido pelo protocolo MCP)
Chamar ferramentas — POST com método tools/call, passando o nome da ferramenta e os argumentos

Todas as requisições devem incluir os headers de autenticação (x-project-key e x-user-key) e, após a inicialização, o header mcp-session-id.

Exemplo: Script de upload em 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();

Salve como upload.mjs e execute:

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

Integração com skill do Claude Code

Se você usa Claude Code, pode encapsular este script como uma skill para que o assistente possa invocá-lo automaticamente quando precisar fazer upload de arquivos. Coloque o script em .claude/skills/sutram-upload/scripts/upload.mjs e crie um SKILL.md que instrua Claude sobre como chamá-lo. Assim, quando o assistente encontrar um arquivo para upload, ele delega o I/O pesado ao script externo enquanto mantém a orquestração na conversa.

Pontos principais

Sem limite de tamanho de arquivo além da cota de armazenamento do seu plano Sutram
Arquivos são enviados diretamente ao S3 via URL pré-assinada — sem codificação base64, sem dados passando pelo servidor web
O script lida com o handshake MCP completo (initialize -> notify -> tool call)
A resposta pode vir como JSON ou Server-Sent Events (SSE) dependendo do tempo de processamento — o script trata ambos
Credenciais podem ser lidas do .mcp.json para evitar hardcoding

REST API

Além das ferramentas MCP, o Sutram fornece uma REST API para consumo somente leitura do conteúdo do projeto. Ela usa a mesma autenticação de chave dupla e é ideal para aplicativos externos, dashboards e scripts.

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

Endpoints:

Endpoint	Descrição
`GET /api/v1/project`	Informações do projeto
`GET /api/v1/folders`	Lista pastas raiz
`GET /api/v1/folders/:id`	Detalhes da pasta com subpastas e itens
`GET /api/v1/content`	Lista itens de conteúdo com filtragem, busca por tag e paginação
`GET /api/v1/content/:id`	Detalhes do item de conteúdo com URLs de download pré-assinadas

Documentação completa: Referência da REST API v1