---
title: MCP
description: Veja as ferramentas, operações e escopos que o agente recebe.
sidebar:
  order: 2
---

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 é:

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

## Identidade do servidor [#server-identity]

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](https://www.callscript.dev/) é o mecanismo de `execute` e `search`, não a marca do produto.

## Superfície de Capacidades [#capability-surface]

- **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 [#authorization-flow]

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:

1. **Adicionar Endpoint**: Configure seu cliente com a URL do servidor `https://www.siglata.com/v1/mcp`.
2. **Iniciar OAuth**: O cliente abre uma janela do navegador apontando para o endpoint de autorização do Siglata.
3. **Autenticar**: Entre com o link mágico recebido por e-mail, caso ainda não esteja autenticado.
4. **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.
5. **Aprovar Escopos**: Revise os escopos de capacidade solicitados (por exemplo, `files:read`, `files:write`, `organizations:read`) e aprove o acesso.
6. **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 [#cli-device-authorization]

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`.

1. `POST /auth/device/code` com `client_id`, `scope` e `resource` definido como `https://www.siglata.com/v1/mcp`.
2. Abra `verification_uri` (ou `verification_uri_complete`) no navegador — o Siglata serve `/app/device`. Entre, selecione uma organização se necessário e aprove.
3. 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 [#oauth-scopes]

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-reference]

`tools/list` anuncia exatamente duas ferramentas, baseadas em [CallScript](https://www.callscript.dev/):

- **`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.

```js title="Um script execute agrupando duas operações"
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 [#resources]

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 [#watching-files]

`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 [#install]

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](/docs/agents/connect).

- Comprovados (v1): [Cursor](/docs/agents/install/cursor), [Codex](/docs/agents/install/codex)
- Instaláveis / compatíveis com a especificação: [ChatGPT Desktop](/docs/agents/install/chatgpt-desktop), [Claude Desktop](/docs/agents/install/claude-desktop), [VS Code](/docs/agents/install/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 [#security]

- **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 [#changing-scopes]

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 [#mcp-registry]

O servidor está listado no MCP Registry oficial como [com.siglata/mcp](https://registry.modelcontextprotocol.io/v0.1/servers/com.siglata%2Fmcp/versions/latest).