MCP: Integraciones y Broker

Una sola tool cubre los sistemas externos por MCP: driftless_broker. Opera una Connection que ya existe, y nunca conecta ni desconecta una (el setup es un flujo liderado por humanos en el dashboard o la CLI, no en la superficie de MCP). Si un agente necesita una operación que la tool no lista, tiene que reportar la capability faltante, nunca escribir un script.

El Broker está gated: apagado por defecto en producción (DRIFTLESS_BROKER_ENABLED), con una lane externa aparte (DRIFTLESS_BROKER_ROLLOUT) y grants por principal. Una acción listada no es una utilizable: un caller OAuth/MCP sin rostro y sin grant obtiene un resultado vacío incluso contra una connection saludable.

La tool broker

driftless_broker es basada en action: pasa action para elegir la operación. Las credenciales se resuelven del lado del servidor y cada llamada queda auditada. El setup (connect / disconnect) y escribir scripts de Nango son carriles separados, solo para humanos, no alcanzables aquí.

Acciones

Acción	Propósito	Efecto
`connections`	Lista las Connections del workspace con salud, criterion y siguientes acciones	read
`context`	El contexto efectivo de la connection: criterion resuelto a trust/staleness y siguiente acción (léelo ANTES de trabajar con el provider)	read
`operations`	Lista las operaciones de un provider, o busca entre providers	read
`capabilities`	El capability directory (kinds, efectos, estados, gates)	read
`inspect`	Spec completa de una operación (schema, efecto, riesgo, idempotencia)	read
`invoke`	Ejecuta una operación con nombre inline (lectura o escritura)	read / write
`models`	Record models importables (syncs habilitados)	read
`records`	Lee los records de un modelo sincronizado desde el mirror	read
`document-content`	Lee el texto acotado y citable de un documento, en vivo (cualquier content provider)	read
`page-content`	Alias DEPRECADO y exclusivo de Notion para `document-content`	read
`index-preview`	Index en seco: conteos y muestras candidatas	read
`index`	Materializa connector documents (propios de Driftless)	admin
`import`	Importa records del mirror a una Collection (connector mapping guardado)	write
`events`	El feed de eventos entrantes del provider	read
`attach-criterion` / `detach-criterion`	Adjunta o quita un slug de criterion de Knowledge en una Connection	admin

driftless_broker action:'connections'
driftless_broker action:'capabilities' provider:'notion'   → solo una capability `ready` es utilizable

Gates y permisos

Tres gates independientes y fail-closed aplican a un caller externo, en orden: el interruptor maestro (DRIFTLESS_BROKER_ENABLED), la lane externa (DRIFTLESS_BROKER_ROLLOUT) y un grant por principal. Una operación además debe estar permitida por la política; en producción el registry de política va vacío, así que ninguna escritura es invocable.

Scope	Cubre
`broker:read`	`connections`, `context`, `operations`, `capabilities`, `inspect`, `models`, `records`, `document-content`, `page-content`, `events`
`broker:invoke`	`invoke` (una operación de lectura o escritura), `import`
`broker:admin`	`attach-criterion` / `detach-criterion`, `index-preview`, `index` (indexar selecciona lo que el workspace puede recuperar/citar: administración de la connection, no invocación); los grants son owner/admin

Los scopes broker:* se aplican solo cuando el Broker está habilitado, y gobiernan la lane encima del rollout y los grants. Un caller interno (una API key propia o una sesión de dashboard) se salta el gate de grant pero igual necesita el resto.

Lecturas y materialización

Las lecturas difieren en si tocan al provider en vivo y en qué crean. records lee el mirror/cache; document-content lee en vivo mediante la ruta de documentos general para providers; index materializa connector documents propios de Driftless; import mapea records del mirror a Records de Collection. El retrieve de contexto normal nunca consulta un provider, y cuando una consulta de retrieve coincide con connector documents indexados que no pediste, la respuesta sugiere sources:['connectors'] en next_action en vez de incluirlos.

driftless_broker action:'context' provider:'notion'                                       → lee primero el criterion
driftless_broker action:'records' provider:'notion' model:'ContentMetadata' limit:5       → desde el mirror
driftless_broker action:'document-content' provider:'notion' external_id:'<id>'           → en vivo, acotado, citado
driftless_broker action:'import' provider:'notion' collection_id:'<uuid>'                 → mirror → Records de Collection

Disponibilidad

Capacidad	Estado
Tool `driftless_broker` listada	Solo cuando `DRIFTLESS_BROKER_ENABLED` está encendido
Lecturas de Notion (`records`, `document-content`, `index`)	Beta, read-only
Escrituras del Broker (`invoke` de una op de escritura) en producción	Not available (el registry de política va vacío)
Tools de lectura sintetizadas por workspace (`driftless_<provider>_records`, `driftless_<provider>_document_content`)	Available solo cuando la síntesis está habilitada y una capability está `ready`
Síntesis de capabilities de escritura	Not available (nunca se sintetizan)

Relacionado

Integraciones y Connections, Broker - el modelo y la semántica.
Use external context in operational work - el workflow.
CLI: Integraciones y Broker, API: Broker y Connections - las otras superficies.
MCP & OAuth - setup, auth y scopes.

Primeros pasos

Conectar

Conceptos

Trabajar y colaborar

Guías

Agentes

Referencia MCP

Referencia CLI

Referencia API

Plataforma

MCP: Integraciones y Broker

La tool broker

Acciones

Gates y permisos

Lecturas y materialización

Disponibilidad

Relacionado

​La tool broker

​Acciones

​Gates y permisos

​Lecturas y materialización

​Disponibilidad

​Relacionado

La tool broker

Acciones

Gates y permisos

Lecturas y materialización

Disponibilidad

Relacionado