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
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 |
| Projects y operaciones | El loop de cards del project, collections, records y entities | MCP: Projects 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 |
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.
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>_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.
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" }
] }
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.
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.driftless.icu/mcp",
"headers": {
"X-API-Key": "drift_your_api_key_here"
}
}
}
}
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:
- Ingresa
https://api.driftless.icu/mcp como el endpoint MCP en Claude.ai
- Claude.ai 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
- 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:
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 |
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
