MCP y OAuth

Driftless incluye un servidor MCP (Model Context Protocol) que expone el contexto de tu workspace a clientes de IA. ChatGPT, Claude, Copilot y cualquier cliente compatible con MCP pueden leer y escribir topics a través de él.

Cómo funciona

El adaptador de MCP corre en apps/mcp y traduce las llamadas a herramientas de MCP hacia la REST API existente de Driftless. Es solo un adaptador de protocolo: nunca accede a Postgres, a librerías internas ni a operaciones de admin del workspace de forma directa.

Empieza por acá: retrieve

Cuando tienes una tarea pero todavía no un slug de topic, la primera llamada es driftless_context_retrieve: devuelve el contexto registrado más relevante del equipo para una descripción de tarea, un conjunto de archivos, o ambos, ordenado con lo drifteado primero y acotado. Compone search + match-files + list filters para que no los encadenes a mano. Los cuerpos vuelven brief por defecto (el porqué durable, no el content completo); llama a driftless_context_get para el único topic cuyo cuerpo completo necesites, o pasa view: "full". El mismo contrato active-only, acotado, brief por defecto aplica a Collections: driftless_collection list es active-only (opta a archived con include_archived:true), y get es brief salvo que pases view:'full'. Ver Payload views más abajo.

Familias de herramientas

La superficie de MCP está documentada por familia en la Referencia MCP. Usa esta página para setup y auth; abre una página de familia para nombres de tools, actions, parámetros, permisos y ejemplos.

Familia	Qué cubre	Referencia
Knowledge y gobernanza	Retrieve, lectura, escritura, grafo, salud, tags, areas y el ciclo de vida Nota a Knowledge	MCP: Knowledge y gobernanza
Collections y operaciones	Collections, records y entities	MCP: Collections y operaciones
Integraciones y Broker	Operar un provider conectado (gated)	MCP: Integraciones y Broker
Workspace y colaboración	Comments, members, workspaces y estadísticas de propuestas	MCP: Workspace y colaboración
Uso comercial	`driftless_usage` consulta el plan, solicitudes, créditos, renovación, investigación promocional y la acción para hablar con ventas. La consulta no consume saldo.	Resumen de la API
Market data	Trece tools tipadas `driftless_market_*` para análisis más `driftless_contact_quote` y `driftless_contact_unlock`. No hay router genérico, detalle masivo de proveedores, selectores físicos ni coordenadas de contacto en el análisis. Reconecta los clientes después de cambios de schema porque pueden guardar definiciones de tools en caché.	Market Data

La superficie cubre el contexto (topics, governance, el grafo), la superficie de trabajo (tags y areas), el sustrato operacional (collections, records, entities), y la ejecución del broker (operar providers conectados). Nunca cubre la administración del workspace, el registro de repos, la gestión de keys, el setup de integración (conectar un provider), escribir/desplegar scripts de integración, ni disparar corridas de agentes a mano. Los topics viven en el workspace y son visibles para sus miembros; los drafts privados de otra persona quedan ocultos. Las escrituras en la superficie de trabajo requieren el scope work:write; mergear a Knowledge requiere autoridad de owner/admin, y el cliente MCP lo corre solo cuando el owner/admin que autoriza lo pide de forma explícita. Cada resultado (search, list, get) lleva un campo plano trust (reviewed | proposed | draft), para que un agente pueda basarse en trust === "reviewed" directamente en vez de inferirlo desde classification.status + governance.authoritative. reviewed es Knowledge, la fuente de verdad del equipo; proposed/draft son Notas (pistas).

Las vistas de payload mantienen las lecturas rápidas

Las lecturas devuelven por defecto un payload liviano para que un resultado nunca inunde tu contexto. El vocabulario es el mismo en todos lados (summary / brief / full):

summary: una fila índice (id/slug, título, trust, badges, anchors). Las listas y la búsqueda devuelven esto, acotado (5 primeros en search, 40 primeros en list).
brief (el default para driftless_context_retrieve y driftless_context_get_for_files) es el porqué durable: what / decisions / gotchas / invariants, sin el content completo. Aproximadamente 76% más liviano que un cuerpo completo.
full: todo, incluyendo el pesado cuerpo content. Nunca es default en otro lado; entras a él con view: "full". driftless_context_get es la excepción: usa full por defecto porque nombraste el único topic que querías. El mismo opt-in view: "full" aplica a driftless_collection action:'get' (brief por defecto, full a pedido).

El patrón: retrieve / get_for_files en brief para ver cuál topic gobierna el trabajo, y después driftless_context_get (full) para el único cuerpo que de verdad necesitas, en vez de traer todos los cuerpos completos de entrada. La superficie de trabajo lo refleja — driftless_collection action:'get' en brief, view:'full' para la única collection cuya config completa necesitas.

Broker (ejecución) vs setup de integración

driftless_broker solo opera una conexión que ya existe (operations / invoke / records / events / criterion). Conectar un provider es setup de integración: un flujo privilegiado y liderado por humanos que se hace en el dashboard (Settings → Connections) o vía los comandos integration connect/confirm del CLI; no está en la superficie de MCP. Escribir o desplegar una acción de Nango es un tercer carril, solo para humanos. Si un agente necesita una operación del broker que operations no lista, tiene que reportar la capacidad que falta. Nunca escribas ni despliegues un script para tapar el hueco.

Las connector tools se sintetizan por workspace

Más allá de las tools estáticas de arriba, el servidor MCP puede sintetizar tools de solo lectura por workspace a partir de las capabilities ready de un provider: driftless_<provider>_records y driftless_<provider>_document_content (por ejemplo, driftless_notion_document_content). Aparecen solo cuando la síntesis de tools del broker está habilitada y el provider expone una capability ready, de efecto lectura y de un kind sintetizable, con un tope por workspace. De ahí dos reglas: una tool listada no es una tool utilizable (una tool sintetizada o la estática del broker igual se resuelve por la API del broker, donde un caller externo está gated por rollout y grants), y las capabilities de escritura nunca se sintetizan. Ver Broker.

Relaciones tipadas desde el MCP

create y update aceptan rels, aristas tipadas del grafo, los mismos siete tipos que el --rel del CLI:

{ "topic": "refund-flow", "rels": [
  { "to": "billing-flow", "type": "depends_on" },
  { "to": "stripe-webhook-ingest", "type": "relates_to" }
] }

Tipos: relates_to, depends_on, supersedes, blocks, implements, documents, risk_for. Cada arista se crea con tolerancia por relación: una arista mala reporta {ok: false, error} en el resultado de la herramienta sin perder el topic ni las aristas restantes. Ambos extremos deben existir y ser visibles para ti.

Validación de anchors del lado del servidor

Los agentes remotos no tienen un checkout local, así que las respuestas de escritura llevan anchor_validation, conteos de coincidencias por patrón contra la rama default del repo: ok, overbroad (>100 archivos), o zero. Las advertencias nunca bloquean la escritura (un glob que ancla código de una rama sin mergear muestra 0 de forma legítima); léelas en el resultado de la herramienta y aprieta los globs marcados. Donde el deployment no tiene índice de archivos del repo vinculado, el campo llega como { skipped } con la razón en vez de conteos — un «no se midió» honesto, nunca un pase silencioso.

Los clientes MCP (claude.ai, ChatGPT) cachean los schemas de herramientas por sesión de conector. Después de que Driftless publica un cambio de schema, reconecta el conector (o arranca una sesión nueva) para tomarlo. Si no, herramientas retiradas pueden seguir apareciendo. Las herramientas de la superficie de trabajo (tags, areas, driftless_collection, driftless_collection_record) son basadas en action: pasa action para elegir la operación.

Governance desde el MCP

Un topic se vuelve Knowledge solo cuando un owner/admin lo mergea. Un cliente MCP siempre pone una Nota en revisión (driftless_context_propose); también puede mergear (driftless_context_approve), pero solo con autoridad de owner/admin. El token de MCP actúa como el humano que lo autorizó, así que approve tiene éxito solo cuando ese humano es owner/admin, y el cliente debería correrlo solo cuando lo piden de forma explícita (el token de un miembro o uno sin identidad se rechaza). El merge queda estampado con approved_via: agent. Ver Governance.

Autenticación

Todas las solicitudes MCP requieren autenticación. Las solicitudes sin autenticar reciben un HTTP 401 con un header WWW-Authenticate que apunta a los endpoints de discovery de OAuth. Hay dos formas de autenticarse:

API key: pasa tu API key de Driftless en el header X-API-Key. Ideal para el CLI, agentes y CI.
OAuth 2.0: para clientes de IA publicados (ChatGPT, Claude) que necesitan consentimiento por usuario. El servidor soporta registro dinámico de clientes y PKCE.

Conectando con una API key

Agrega esto a tu claude_desktop_config.json o equivalente:

{
  "mcpServers": {
    "driftless": {
      "url": "https://api.trybrein.com/mcp",
      "headers": {
        "X-API-Key": "drift_your_api_key_here"
      }
    }
  }
}

Para desarrollo local, usa http://localhost:3020/mcp y tu API key local.

Conectando con OAuth (Claude.ai, ChatGPT)

La aplicación publicada en ChatGPT se llama Brein. Se conecta al mismo espacio de trabajo autenticado de Driftless y usa los mismos permisos y contratos de herramientas MCP; el nombre no crea una segunda cuenta ni otra frontera de datos. Los clientes publicados usan OAuth 2.0 con PKCE. El flujo es totalmente automático:

Instala Brein en ChatGPT, o ingresa https://api.trybrein.com/mcp como el endpoint MCP en Claude.ai
El cliente descubre los endpoints de OAuth automáticamente vía /.well-known/oauth-protected-resource y /.well-known/oauth-authorization-server
Autorizas en la pantalla de consentimiento de Driftless
El cliente recibe un bearer token y lo usa para las llamadas MCP dentro del espacio de trabajo autorizado

No hace falta configuración OAuth manual. El cliente maneja el registro, PKCE y el refresh de tokens.

Referencia de OAuth 2.0

Registro dinámico de clientes

Cualquier cliente puede registrarse sin autenticación:

curl -X POST https://api.trybrein.com/api/v1/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Mi Cliente de IA",
    "redirect_uris": ["https://myapp.com/oauth/callback"]
  }'

Scopes de OAuth

Scope	Descripción
`context:read`	Lee topics y contexto
`topics:create`	Crea topics nuevos
`topics:write`	Actualiza topics existentes
`work:write`	Escribe la superficie de trabajo: collections, records, entities, comentarios, tags, areas, más las acciones de merge y share
`context:diff`	Lee el diff de topics para cambios locales
`broker:read`	Lee connections, capabilities y records del broker
`broker:invoke`	Invoca una operación del broker
`broker:admin`	Gestiona grants y criterion del broker
`market_data:read`	Lee inteligencia comercial (suppliers, opportunities, awards, marcas de riesgo, permits) — ver Market Data
`commercial:read`	Lee una cotización exacta de Contact Path para registros CRM seleccionados; nunca devuelve coordenadas de contacto.
`offline_access`	Refresca el acceso sin reconectar

Los scopes broker:* se aplican solo cuando el Broker está habilitado, y gobiernan su lane encima del rollout y los grants. La metadata de discovery anuncia un subconjunto de scopes; el conjunto aplicado es la autoridad. market_data:read es el scope documentado y canónico para las lecturas de market-data, pero la emisión OAuth por defecto de hoy todavía no lo otorga — context:read sigue satisfaciendo esas rutas de forma transicional para que ningún caller existente se rompa.

Endpoints

Método	Path	Propósito
`GET`	`/.well-known/oauth-protected-resource`	Metadata del recurso MCP (RFC 9728)
`GET`	`/.well-known/oauth-authorization-server`	Metadata del authorization server (RFC 8414)
`GET`	`/.well-known/openid-configuration`	Alias de discovery compatible con OIDC
`GET`	`/api/v1/oauth/authorize`	Pantalla de consentimiento de autorización (redirige al dashboard)
`POST`	`/api/v1/oauth/token`	Intercambia el code por un access token
`POST`	`/api/v1/oauth/register`	Registra un cliente OAuth (RFC 7591)
`POST`	`/api/v1/oauth/revoke`	Revoca un access token

Seguridad de tokens

Los authorization codes, access tokens y refresh tokens se guardan solo como hashes, nunca en texto plano
Los tokens nunca se loguean ni se devuelven después de la emisión inicial
El servidor MCP no importa @driftless/db, typeorm ni ninguna librería interna; llama exclusivamente a la REST API

Primeros pasos

Conectar

Conceptos

Trabajar y colaborar

Guías

Agentes

Referencia MCP

Referencia CLI

Referencia API

Plataforma

Cómo funciona

Empieza por acá: retrieve

Familias de herramientas

Las vistas de payload mantienen las lecturas rápidas

Broker (ejecución) vs setup de integración

Las connector tools se sintetizan por workspace

Relaciones tipadas desde el MCP

Validación de anchors del lado del servidor

Governance desde el MCP

Autenticación

Conectando con una API key

Conectando con OAuth (Claude.ai, ChatGPT)

Referencia de OAuth 2.0

Registro dinámico de clientes

Scopes de OAuth

Endpoints

Seguridad de tokens

​Cómo funciona

​Empieza por acá: retrieve

​Familias de herramientas

​Las vistas de payload mantienen las lecturas rápidas

​Broker (ejecución) vs setup de integración

​Las connector tools se sintetizan por workspace

​Relaciones tipadas desde el MCP

​Validación de anchors del lado del servidor

​Governance desde el MCP

​Autenticación

​Conectando con una API key

​Conectando con OAuth (Claude.ai, ChatGPT)

​Referencia de OAuth 2.0

​Registro dinámico de clientes

​Scopes de OAuth

​Endpoints

​Seguridad de tokens

Cómo funciona

Empieza por acá: retrieve

Familias de herramientas

Las vistas de payload mantienen las lecturas rápidas

Broker (ejecución) vs setup de integración

Las connector tools se sintetizan por workspace

Relaciones tipadas desde el MCP

Validación de anchors del lado del servidor

Governance desde el MCP

Autenticación

Conectando con una API key

Conectando con OAuth (Claude.ai, ChatGPT)

Referencia de OAuth 2.0

Registro dinámico de clientes

Scopes de OAuth

Endpoints

Seguridad de tokens