> ## Documentation Index > Fetch the complete documentation index at: https://docs.trybrein.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP y OAuth > Conecta ChatGPT, Claude y otros clientes de IA a tu workspace de Driftless a través del Model Context Protocol. 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](#payload-views-keep-reads-fast) 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](/es/mcp/knowledge) | | Collections y operaciones | Collections, records y entities | [MCP: Collections y operaciones](/es/mcp/work) | | Integraciones y Broker | Operar un provider conectado (gated) | [MCP: Integraciones y Broker](/es/mcp/integrations) | | Workspace y colaboración | Comments, members, workspaces y estadísticas de propuestas | [MCP: Workspace y colaboración](/es/mcp/collaboration) | | 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](/es/api/overview#uso-comercial) | | 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](/es/api/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__records` y `driftless__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](/es/integrations/broker). ### Relaciones tipadas desde el MCP `create` y `update` aceptan `rels`, aristas tipadas del grafo, los mismos siete tipos que el `--rel` del CLI: ```json theme={"theme":"github-light"} { "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](/es/concepts/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: ```json theme={"theme":"github-light"} { "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: 1. Instala Brein en ChatGPT, o ingresa `https://api.trybrein.com/mcp` como el endpoint MCP en Claude.ai 2. El cliente descubre los endpoints de OAuth automáticamente vía `/.well-known/oauth-protected-resource` y `/.well-known/oauth-authorization-server` 3. Autorizas en la pantalla de consentimiento de Driftless 4. 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: ```bash theme={"theme":"github-light"} 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](/es/api/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