MCP

Veja as ferramentas, operações e escopos que o agente recebe.

O Model Context Protocol (MCP) permite que agentes de IA e ferramentas de desenvolvimento acessem suas organizações e arquivos no Siglata. O servidor usa Streamable HTTP e OAuth 2.0. Os escopos de permissão e a verificação de vínculo com a organização determinam o que cada conexão pode acessar.

O endpoint de produção do MCP é:

https://www.siglata.com/v1/mcp

Identidade do servidor

Este servidor publica strings de identidade distintas em cada camada.

Camada	String atual	Quem lê
Product / title	`Siglata` (`serverInfo.title`)	Clientes MCP que exibem um título de produto
Protocol server name	`siglata` (MCP `initialize` / `serverInfo.name`)	Clientes MCP durante `initialize`
Script engine	`CallScript` (`callscript` npm)	Chamadores de `execute` e `search`
Registry package id	`com.siglata/mcp`	Registros MCP
Plugin / skill key	`siglata`	Carregadores de plugin e skill de agentes

CallScript é o mecanismo de execute e search, não a marca do produto.

Superfície de Capacidades

Nome do servidor: siglata.
Ferramentas: exatamente duas, execute e search.
Operações: operações de gerenciamento, chamáveis dentro de scripts execute e não como ferramentas MCP.
Contexto de organização: Chame principal_get dentro de um script execute para saber a qual organização esta concessão está vinculada (organizationId), além de userId, role e scopes. Chame organization_get para o nome ou o slug da organização vinculada. Chame organizations_list para ver todas as organizações às quais o usuário autorizador pertence; o sinalizador current marca a organização vinculada à concessão. Listar não troca a concessão — outro espaço de trabalho exige uma nova conexão OAuth autorizada com essa organização ativa no consentimento.
Recursos: um template, siglata:///files/{fileId}, para concessões com files:read. O servidor não expõe listagem de recursos. subscriptions/listen sobre esses URIs (até 64 por stream) emite notifications/resources/updated quando os metadados ou a legibilidade de um arquivo observado mudam; o stream permanece vinculado à validade da concessão e da sessão.
Prompts: um, siglata-callscript — o fluxo de trabalho CallScript search → execute como mensagem de usuário reutilizável.
DPoP: opcional. A prova é validada e o token vinculado à sua chave quando o cliente apresenta uma, e tokens bearer simples continuam funcionando.

Fluxo de Autorização e Conexão

A conexão de um cliente MCP utiliza um fluxo padrão de código de autorização OAuth 2.0 em conformidade com as RFCs:

Adicionar Endpoint: Configure seu cliente com a URL do servidor https://www.siglata.com/v1/mcp.
Iniciar OAuth: O cliente abre uma janela do navegador apontando para o endpoint de autorização do Siglata.
Autenticar: Entre com o link mágico recebido por e-mail, caso ainda não esteja autenticado.
Selecionar Organização: Escolha a organização específica que esta conexão poderá acessar. Cada concessão é estritamente vinculada a um único ID de organização.
Aprovar Escopos: Revise os escopos de capacidade solicitados (por exemplo, files:read, files:write, organizations:read) e aprove o acesso.
Entrega do Token: O cliente recebe um token de acesso delimitado exclusivamente à organização escolhida.

┌────────────────┐        1. Fluxo OAuth       ┌──────────────────┐
│   Cliente MCP  │ ──────────────────────────> │  Autenticação    │
│ (Claude/Cursor)│ <────────────────────────── │  (Siglata Auth)  │
└────────────────┘      2. Token Delimitado    └──────────────────┘
        │
        │ 3. JSON-RPC (POST /v1/mcp)
        ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Servidor MCP Siglata                        │
│  - Verificação de Origem e Validação de Sessão                  │
│  - Checagem Dinâmica de Associação e Políticas de Escopo        │
│  - Isolamento Estrito de Limite Organizacional                  │
└─────────────────────────────────────────────────────────────────┘
        │                                 │
        ▼                                 ▼
┌──────────────────┐              ┌──────────────────┐
│   Arquivos       │              │  Organização     │
│ (Blocos de 8MiB) │              │ (RBAC / Convites)│
└──────────────────┘              └──────────────────┘

Autorização de dispositivo para CLI

CLIs sem navegador usam a concessão de autorização de dispositivo OAuth 2.0 (urn:ietf:params:oauth:grant-type:device_code). Registre um cliente público (token_endpoint_auth_method: none) cujos grant_types incluam essa concessão (e refresh_token se precisar renovar). A descoberta anuncia device_authorization_endpoint.

POST /auth/device/code com client_id, scope e resource definido como https://www.siglata.com/v1/mcp.
Abra verification_uri (ou verification_uri_complete) no navegador — o Siglata serve /app/device. Entre, selecione uma organização se necessário e aprove.
Faça polling em POST /auth/oauth2/token com grant_type=urn:ietf:params:oauth:grant-type:device_code até receber o access token. Não use /auth/device/token para MCP; esse endpoint não é o caminho OAuth do MCP.

O JWT emitido tem aud = o recurso MCP e organizationId congelado na organização ativa no momento da aprovação. Mudar a organização ativa depois não reassocia uma concessão de dispositivo existente — autorize de novo para outro espaço de trabalho.

Clientes IDE com código de autorização continuam usando /oauth2/authorize → /app/consent sem mudanças.

Escopos OAuth

O Siglata aplica escopos de capacidade fundamentados no princípio do menor privilégio:

Escopo	Descrição	Função Mínima
`files:read`	Inspecionar arquivos ativos, listar lixeira, consultar métricas de armazenamento e obter URLs autenticadas de download.	`member`
`files:write`	Reservar uploads, concluir transferências, cancelar uploads, renomear arquivos, mover para lixeira e restaurar arquivos.	`member`
`organizations:read`	Ler perfil e metadados da organização concedida.	`member`
`organizations:write`	Atualizar nome ou slug da organização, ou criar novas organizações.	`admin`
`members:read`	Listar membros da organização e visualizar convites pendentes.	`member`
`members:write`	Convidar novos membros, cancelar convites pendentes, atualizar funções ou remover membros.	`admin`

Além dos escopos OAuth, o Siglata valida sua associação ativa na organização em tempo real a cada operação. Se a função de um usuário for alterada ou o acesso for revogado, a operação será bloqueada imediatamente. O MCP de produto também exige nível de acesso por organização (testing ou upgraded); organizações com status revoked (linhas ausentes passam a testing) falham com MCP_ACCESS_REVOKED.

Referência de Ferramentas e Operações

tools/list anuncia exatamente duas ferramentas, baseadas em CallScript:

execute executa um script que agrupa operações de gerenciamento em uma única chamada. As chamadas rodam no servidor e se compõem: um script pode listar arquivos e depois renomear ou mover cada resultado — apenas o valor retornado atravessa a rede.
search lista as assinaturas das operações que esta concessão pode chamar, para que o cliente descubra seu conjunto disponível sem tentativas.

const trash = await files_list({ state: "trash" });
const storage = await storage_get({});
return { trash, storage };

As operações abaixo são funções dentro de scripts execute — chamar uma delas diretamente pelo nome via tools/call retorna um erro JSON-RPC com error.code -32602 e error.data.code USE_EXECUTE, redirecionando o chamador para execute. Uma operação cujo escopo ou função de membro exigidos esteja ausente nunca é montada para a concessão: search não a lista e um script que a nomeie falha na validação. Os cartões do search declaram os códigos de falha de cada operação, e scripts contendo passos suspend são rejeitados como invalid — escreva scripts de passagem única.

Chame search para obter o cartão de assinatura de cada operação que esta concessão pode chamar — parâmetros, formatos de retorno e códigos de falha declarados — filtrado pelos escopos e pela função da concessão.

Arquivos

Operação	Descrição
`files_list`	Lista arquivos ativos ou itens recuperáveis da lixeira na organização.
`uploads_list`	Lista uploads não finalizados para que possam ser retomados ou cancelados.
`storage_get`	Consulta as métricas atuais de armazenamento da organização em bytes.
`file_get`	Lê os metadados e o estado de ciclo de vida de um arquivo.
`folder_get`	Lê os metadados e o estado de ciclo de vida de uma pasta.
`file_read`	Lê os bytes de um arquivo inline, ou retorna instruções autenticadas de transferência para arquivos maiores.
`sheet_list`	Lista as planilhas de um `.xlsx` armazenado sem devolver os bytes do workbook.
`sheet_read`	Lê um intervalo A1 de um `.xlsx` armazenado como células JSON sem devolver os bytes do workbook.
`sheet_write`	Aplica um ou mais patches em intervalos A1 (`patches[]`) de um workbook existente, preserva as células fora desses intervalos e as abas não tocadas, e devolve o id de arquivo de uma nova edição sem devolver os bytes do workbook.
`relation_extract`	Extrai tabelas de relação nomeadas de workbooks `.xlsx` armazenados, um resultado por seção solicitada; `persist` armazena cada seção extraída para consultas posteriores.
`relation_query`	Consulta uma relação persistida em um `.xlsx` armazenado com filtros, ordenação e paginação, sem reabrir o workbook.
`doc_list`	Conta os parágrafos do corpo de um `.docx` armazenado sem devolver os bytes do documento.
`doc_read`	Lê o texto simples dos parágrafos de um `.docx` armazenado sem devolver os bytes do documento.
`pdf_list`	Conta as páginas de um PDF armazenado sem devolver os bytes do documento.
`pdf_read`	Lê o texto simples das páginas de um PDF armazenado sem devolver os bytes do documento.
`ppt_list`	Lista índices e títulos dos slides de um `.pptx` armazenado sem devolver os bytes do arquivo.
`ppt_read`	Lê o texto simples dos parágrafos dos slides e as `notes` do apresentador de um `.pptx` armazenado sem devolver os bytes do arquivo.
`file_download`	Obtém instruções autenticadas de download HTTP para um arquivo.
`file_write`	Cria um arquivo pequeno inline.
`file_rename`	Renomeia um arquivo sem modificar ou reenviar seus bytes armazenados.
`file_set_visibility`	Define a visibilidade de um arquivo como organizacional ou restrita.
`file_move`	Move um arquivo para uma pasta ou de volta à raiz da organização.
`file_copy`	Copia um arquivo ativo para uma pasta ou a raiz da organização, cobrando a cota de armazenamento pelo tamanho total.
`file_trash`	Move um arquivo ativo para a lixeira recuperável.
`file_restore`	Restaura um arquivo da lixeira para o estado ativo.
`file_purge`	Exclui permanentemente um arquivo da lixeira e libera sua cota de armazenamento.
`upload_begin`	Reserva cota de armazenamento e inicia uma sessão de upload em partes.
`upload_complete`	Finaliza um upload após a transferência de todas as partes.
`upload_cancel`	Cancela um upload não finalizado e libera sua reserva de cota.

Pastas e Acesso

Operação	Descrição
`folders_list`	Lista as pastas da organização.
`folder_create`	Cria uma pasta, opcionalmente aninhada sob uma pasta pai.
`folder_rename`	Renomeia uma pasta sem afetar seu conteúdo.
`folder_set_visibility`	Define a visibilidade de uma pasta como organizacional ou restrita.
`folder_move`	Move uma pasta para uma nova pasta pai ou de volta à raiz da organização.
`folder_copy`	Copia em profundidade uma pasta ativa e retorna apenas a nova pasta raiz.
`folder_trash`	Move uma pasta para a lixeira recuperável.
`folder_restore`	Restaura uma pasta da lixeira antes do prazo de recuperação.
`folder_purge`	Exclui permanentemente uma pasta da lixeira.
`grants_list`	Lista as concessões de acesso explícitas de um arquivo ou pasta.
`grant_create`	Concede a um membro acesso de leitura ou escrita a um arquivo ou pasta.
`grant_revoke`	Revoga uma concessão de acesso.

Organização e Equipe

Operação	Descrição
`principal_get`	Lê a identidade, a função e os escopos vinculados a esta concessão.
`organization_get`	Retorna os detalhes da organização selecionada.
`organizations_list`	Lista as organizações às quais o usuário autorizador pertence; `current` marca a organização vinculada à concessão sem trocá-la.
`organization_update`	Atualiza o nome ou slug da organização selecionada.
`organization_create`	Cria uma nova organização.
`organization_delete`	Exclui permanentemente a organização selecionada e seus arquivos. Somente proprietário.
`members_list`	Lista os membros da organização com paginação.
`member_update_role`	Altera a função de um membro na equipe.
`member_remove`	Remove um membro da organização.
`invitation_create`	Convida um novo membro para a organização por e-mail.
`invitation_resend`	Reenvia o e-mail de um convite pendente da organização selecionada.
`invitations_list`	Lista todos os convites pendentes da organização.
`invitation_cancel`	Cancela um convite ainda não aceito.
`invitations_mine`	Lista os convites pendentes endereçados ao usuário autorizador (podem incluir outras organizações).
`invitation_accept`	Aceita um convite pendente somente da organização vinculada à concessão. Não religa a concessão OAuth; aceitar outra organização exige aceite no console e uma nova concessão.
`invitation_reject`	Rejeita um convite pendente somente da organização vinculada à concessão. Não religa a concessão OAuth.
`organization_leave`	Sai da organização vinculada à concessão. A próxima chamada MCP falha por falta de associação.
`sessions_list`	Lista as sessões de concessão MCP ativas do próprio principal.
`session_revoke`	Revoga uma das suas próprias sessões de concessão MCP.

Recursos

Concessões com files:read também veem um modelo de recurso, siglata:///files/{fileId}, que resolve os bytes de um arquivo via resources/read. Mídias textuais retornam texto decodificado e demais mídias retornam base64 para arquivos de até 1 MiB; arquivos maiores resolvem nas mesmas instruções autenticadas de transferência de file_read. A concessão é verificada novamente a cada leitura.

Observando arquivos

subscriptions/listen sobre URIs siglata:///files/{fileId} abre um stream server-sent que emite notifications/resources/updated quando um arquivo observado muda. O stream honra até 64 URIs; URIs fora do modelo, ou qualquer assinatura em uma concessão sem files:read, são rejeitados antes de o stream abrir.

A primeira observação de cada URI é uma linha de base e nunca emite. Depois disso, uma notificação é emitida quando os metadados de um arquivo mudam, quando ele se torna ilegível para esta concessão (excluído, restrito ou com a concessão revogada) e quando volta a ser legível. Estados idênticos ou repetidamente ilegíveis permanecem silenciosos — uma notificação significa “releia o recurso”, nunca um diff de conteúdo.

Cada URI observado é reautorizado em toda avaliação sob a concessão que abriu o stream: um arquivo que você não pode mais ler é indistinguível de um que não existe. Mutações de arquivos enviam um aviso de melhor esforço ao hub de observação para baixa latência; uma varredura periódica verifica novamente cada observador, de modo que um aviso perdido ainda é recuperado. O stream termina quando o cliente desconecta, quando a concessão deixa de resolver (sessão revogada, perda de vínculo à organização) ou no menor entre o vencimento da concessão e uma hora — clientes voltam a escutar para continuar observando.

Instalação

Conecte-se via OAuth a https://www.siglata.com/v1/mcp. Os passos de instalação por cliente ficam em páginas dedicadas (comandos para copiar e colar para pessoas e agentes). Comece em Conectar.

Comprovados (v1): Cursor, Codex
Instaláveis / compatíveis com a especificação: ChatGPT Desktop, Claude Desktop, VS Code

Esta página documenta apenas a superfície MCP (execute, search, operações CallScript, recursos, escopos). Ela não duplica esses guias de instalação.

Segurança e Revogação

Isolamento Multi-Inquilino: Cada concessão MCP permite acesso a exatamente uma organização. Para acessar outro espaço de trabalho, autentique uma conexão adicional.
Validação de Estado Ativo: Os tokens são validados contra os registros de sessão no banco de dados e a associação ativa na organização a cada solicitação.
Revogação: Uma concessão deixa de funcionar quando a sessão autorizadora termina ou quando o membro sai da organização. Derrube uma conexão pelo próprio protocolo com session_revoke, revogue a sessão com POST /auth/revoke-session ou remova o membro com member_remove; em todos os casos, a próxima requisição do cliente é rejeitada.

Alterando escopos após a autorização

Os escopos são escolhidos no consentimento e armazenados na concessão. Não existe API de mutação de escopos após a concessão (scopes_update ou similar), porque ampliar escopos sem novo consentimento contornaria o limite de confiança do consentimento. Para alterar escopos, revogue a concessão atual com session_revoke (ou revogue a sessão / saia da organização), então execute o OAuth novamente e aprove o conjunto de escopos desejado no consentimento.

MCP Registry

O servidor está listado no MCP Registry oficial como com.siglata/mcp.