> ## Documentation Index > Fetch the complete documentation index at: https://docs.driftless.icu/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"`. 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) | | Projects y operaciones | El loop de cards del project, collections, records y entities | [MCP: Projects 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) | La superficie cubre el **contexto** (topics, governance, el grafo), la **superficie de trabajo** (proyectos, cards, tags, 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 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. ### 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__page_content` (por ejemplo, `driftless_notion_page_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. 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, los parámetros o herramientas nuevos no van a estar disponibles. Las herramientas de la superficie de trabajo (`tags`, `areas`, `project`, `project_card`) son **basadas en `action`**: pasa `action` para elegir la operación; si tu cliente todavía muestra los nombres viejos de herramienta por operación (por ejemplo `driftless_tags_create`), reconecta para refrescar. ### 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.driftless.icu/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) Los clientes publicados usan OAuth 2.0 con PKCE. El flujo es totalmente automático para Claude.ai: 1. Ingresa `https://api.driftless.icu/mcp` como el endpoint MCP en Claude.ai 2. Claude.ai 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. Claude.ai recibe un bearer token y lo usa para todas las llamadas a herramientas de MCP No hace falta configuración manual. Claude.ai 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.driftless.icu/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: proyectos, cards, 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 | | `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. ### 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