Docs Scopes

Los scopes de tabla deciden a qué filas llega una key. Los Docs scopes deciden a qué documentos llega. Son listas separadas, y ninguna implica la otra.

Se configuran en la pestaña Docs de una API key o de un conector de IA.

Por qué los documentos necesitan su propio eje

Los documentos de un workspace no son filas. Viven en un árbol de carpetas y espacios, los editan personas y no integraciones, y lo que va adentro suele ser prosa y no campos — notas de reunión, contratos, especificaciones, la carpeta de un cliente.

Esa diferencia importa para los permisos. Los scopes de tabla son por tabla, y una tabla es algo plano que permitís o no. Los documentos son una jerarquía, y el permiso útil casi siempre es "esta rama, menos esa página".

Por eso el eje de Docs es un árbol de permisos y no una lista.

Sobre qué se puede otorgar

Un permiso apunta a una de cuatro cosas:

Un permiso sobre una carpeta cubre todo lo que hay debajo, recursivamente. No hace falta repetirlo por cada hijo.

Los niveles

Herencia, y la distinción que importa

Esta es la parte que conviene precisar, porque dos situaciones se ven igual en la interfaz y se comportan completamente distinto.

Un destino sin permiso propio hereda del ancestro más cercano que sí tenga uno. No se dijo nada sobre él, así que responde el árbol.

Un destino puesto explícitamente en `None` no hereda. Está bloqueado, aunque su carpeta padre tenga Full.

  Raíz                     (sin permiso)
   └── Clientes            Read          <- todo lo de abajo es legible...
        ├── Acme                         <- hereda Read
        ├── Beta                         <- hereda Read
        └── Interno        None          <- ...menos esta rama

Así decís "toda la carpeta de clientes, menos las notas internas" — un permiso más una exclusión, en vez de listar cada carpeta que sí querés.

Gana el ancestro más cercano, así que un None en el fondo de un árbol permitido recorta exactamente ese subárbol, y un permiso dentro de un subárbol en None vuelve a abrir exactamente esa rama.

Una key sin ningún permiso no llega a ningún documento. El default es nada, no todo — una key nueva no puede leer un documento hasta que alguien diga cuál.

Qué significa en la práctica

Otorgá la rama, no las páginas. Un permiso sobre una carpeta sigue funcionando cuando alguien le agrega un documento. Una lista de documentos sueltos deja de cubrir el material nuevo en silencio, y nadie lo nota hasta que a una integración le falta algo que debería haber tenido.

Usá `None` para la excepción, no para la regla. Si terminás escribiendo más exclusiones que permisos, el permiso está en el nivel equivocado — bajalo en el árbol.

Acá lecturas y escrituras son el mismo eje. A diferencia de los scopes de tabla, no hay una lista de lectura y otra de escritura: lo dice el nivel del permiso. Read sobre una carpeta significa que una integración puede resumir todo lo que hay adentro y no cambiar nada, que es el ajuste correcto para la mayoría de los conectores de IA.

Pensá bien antes de usar `Full`. Incluye eliminar, y un documento no es una fila — perder uno pierde prosa que alguien escribió. ReadWrite cubre toda integración que edite documentos; reservá Full para algo cuyo trabajo real sea limpiar.

Docs scopes y herramientas MCP

Los dos se verifican por separado, y los dos tienen que pasar.

Habilitar el grupo de herramientas Docs permite que una key llame a las herramientas de documentos. No otorga ni un solo documento — los Docs scopes siguen decidiendo cuáles ven esas herramientas. Un conector con el grupo Docs y sin Docs scopes puede llamar las herramientas y no va a encontrar nada.

Al revés también: los Docs scopes de una key cuyo grupo Docs está apagado no hacen nada por MCP, porque la llamada se rechaza antes de consultar los scopes.

Cuando falla una lectura de documento sin explicación, revisá los dos — el error te dice cuál eje la detuvo.

Siguiente

• Credenciales y Principales — los tres ejes y cómo se componen.

• Permisos de Herramientas MCP — el modelo de grupos y excepciones.