El servicio MCP

AWR expone su registro de trabajo a través de MCP (Model Context Protocol), el protocolo estándar que permite a un host de agente — como un asistente de programación o un cliente de IA de escritorio — descubrir y llamar herramientas. El servicio MCP es la forma en que tu agente lee el estado del proyecto, compila contexto, registra evidencia y hace avanzar el trabajo sin recurrir a la CLI por sí mismo. Hay dos formas de ejecutarlo:

• stdio — un proceso local que tu cliente lanza directamente, un proyecto cada vez. Es la configuración clásica y sigue disponible.
• HTTP compartido — un único endpoint Streamable HTTP que sirve a varios proyectos y varios clientes independientes. Tanto el paquete de npm como el de PyPI incluyen esta capacidad.

Este artículo se centra en el servicio HTTP compartido, que es lo que ejecutas cuando más de una persona o agente necesita los mismos proyectos. Para lo que los agentes hacen con estas herramientas una vez conectados, consulta Agentes. Para el equivalente orientado a humanos de las mismas operaciones, consulta La CLI de AWR.

Cómo funciona el servicio compartido

Inicializas cada proyecto en el servidor con awr init y luego registras su raíz absoluta canónica junto con el project_id devuelto por:

awr --json status

AWR verifica esa identidad al arrancar y en cada petición. Los archivos fuente y la base de datos .awr de cada proyecto permanecen separados: el servicio no clona repositorios, no monta sistemas de archivos de clientes ni fusiona registros de proyectos. Los clientes necesitan acceso de red al servicio, no un ejecutable local de AWR, y los archivos del proyecto deben ser legibles en el servidor: una ruta en el portátil de un cliente no se vuelve legible en remoto. No hay un «proyecto actual» compartido: cada herramienta de proyecto toma un argumento project explícito, y no hay ninguna herramienta para abrir una ruta arbitraria del servidor.

Configurar el servicio

Crea un archivo TOML propiedad del operador fuera del repositorio público:

version = 1
allowed_hosts = ["awr.internal.example"]

[[projects]]
key = "billing"
root = "/srv/projects/billing"
project_id = "<actual project ID>"

[[projects]]
key = "support"
root = "/srv/projects/support"
project_id = "<actual project ID>"

[[clients]]
id = "engineering"
token_env = "AWR_ENGINEERING_TOKEN"
write = ["billing", "support"]

[[clients]]
id = "reviewer"
token_env = "AWR_REVIEWER_TOKEN"
read = ["billing"]

Cada entrada de cliente nombra una variable de entorno que contiene su credencial bearer. Proporciona credenciales distintas, generadas aleatoriamente, de al menos 32 caracteres. Una concesión de write incluye acceso de lectura; una concesión de read no puede modificar proyectos. Mantén los ID de cliente estables entre rotaciones de credenciales: las vinculaciones de conversación y de petición se asocian al ID de cliente, y cambiarlo crea un ámbito distinto. Los cambios de configuración solo surten efecto tras reiniciar el servicio.

Ejecutar el servicio

awr-mcp --registry /etc/awr/service.toml --listen 127.0.0.1:8080

Toda petición HTTP está autenticada. El mecanismo incorporado es autenticación bearer estática: no un servidor de autorización OAuth ni un proveedor de identidad empresarial. Para acceso remoto, termina HTTPS en una frontera de despliegue autenticada y restringe el acceso directo al backend. Controles de acceso adicionales:

• Los orígenes se rechazan a menos que estén listados explícitamente en allowed_origins; los clientes nativos normalmente omiten la cabecera Origin.
• El SDK comprueba allowed_hosts, con hosts de loopback como valor predeterminado cuando no hay ninguno configurado.
• El servicio valida Origin pero no implementa el preflight CORS del navegador, así que un frontend de navegador necesita una pasarela adecuada.

En Unix, SIGTERM y Ctrl-C dejan de aceptar peticiones con elegancia y drenan el trabajo HTTP activo. Desconectar un cliente o reiniciar el servicio nunca termina una sesión de trabajo AWR: las conexiones de protocolo y las sesiones persistentes son identidades separadas. AWR no instala un demonio del sistema: usa el supervisor de procesos de tu despliegue para el arranque y el reinicio. Para uso local de un solo cliente, el comando stdio sigue siendo:

awr-mcp --project /absolute/project

Conectar un cliente

Configura cada cliente MCP para Streamable HTTP con la misma URL del servicio usando la ruta /mcp, más su propia credencial bearer en una cabecera Authorization: Bearer … entregada a través del mecanismo de credenciales de ese cliente. Una vez conectado, llama a awr_projects_list para descubrir las claves de proyecto para las que tu credencial está autorizada. Cada herramienta de proyecto requiere entonces project:

{"project": "billing", "work": "INVOICE-001"}

Las herramientas

El servicio HTTP compartido expone 21 herramientas en total (20 por stdio, que omite la herramienta de listado de proyectos). Se dividen en tres grupos.

Herramientas de trabajo y contexto

Reflejan las acciones cotidianas de la CLI:

Herramientas de sesión y continuación

Las sesiones vinculan una conversación a una unidad de trabajo. Proporciona un identificador conversation estable desde tu host, no un identificador de conexión HTTP. La misma cadena de conversación bajo otro proyecto o cliente es una vinculación separada.

Una espera pendiente bloquea las transiciones de trabajo y la reanudación hasta que el host registra una respuesta. La respuesta elimina ese bloqueo pero no cambia el estado del trabajo ni programa el siguiente turno del host: tu host inspecciona la sesión, compila contexto nuevo y decide si continuar o crear un sucesor.

Escrituras, revisiones y resultados inciertos

Toda escritura por HTTP compartido requiere dos cosas:

• un request_id estable generado por el cliente (hasta 256 bytes),
• la expected_revision que observaste por última vez.

{
  "project": "billing",
  "request_id": "host-turn-42-start",
  "expected_revision": 120,
  "work": "INVOICE-001",
  "conversation": "invoice-review",
  "agent": "billing-assistant",
  "provider": "example-provider",
  "model": "example-model",
  "claim": true
}

Repetir exactamente el mismo ID de petición y argumentos devuelve el resultado registrado sin ejecutar la acción de nuevo, así que un reintento tras un tiempo de espera es seguro. Los argumentos modificados requieren un ID nuevo. Guarda el project_revision devuelto para tu próxima escritura, y nunca calcules la siguiente revisión sumando uno: el diario de peticiones y la operación de dominio consumen revisiones.

Tras un tiempo de espera o una desconexión, llama a awr_operation_get con el mismo proyecto e ID de petición. Una petición sin terminar informa write_outcome: unknown; una escritura interrumpida puede haberse confirmado ya, así que nunca infieras un fallo a partir de un flujo de respuesta HTTP cerrado. awr_operation_recover puede registrar un resultado confirmado solo cuando un evento terminal inequívoco está vinculado a la petición: nunca vuelve a invocar la herramienta original. Las lecturas pueden ejecutarse en paralelo; las escrituras se serializan por proyecto, y los proyectos distintos tienen bloqueos independientes. Una escritura obsoleta devuelve un conflicto: lee el estado actual y reconsidera antes de reintentar.

Lecturas de líneas de trabajo (en desarrollo)

El árbol de desarrollo añade un registro version = 2 que concede a los clientes acceso de solo lectura a líneas de trabajo inmutables y explícitamente listadas, para proyectos que usan el registro YAML de líneas de trabajo. Son permisos propiedad del operador: las concesiones read/write a nivel de proyecto por sí solas no autorizan ninguna línea de trabajo aislada.

[[clients.workstreams]]
project = "billing"
workstream_id = "<actual immutable workstream ID>"
authority_version = 1

Los clientes autorizados usan la herramienta awr_workstream, exclusiva del servicio compartido, empezando con action: "capabilities" y action: "list" para descubrir qué pueden leer. Ten en cuenta los límites actuales: esta extensión concede solo lecturas — ninguna mutación, lectura de archivos de contenido ni operaciones de Team PostgreSQL — y los proyectos que la activan rechazan las herramientas compartidas heredadas, incluidas todas las escrituras, hasta que haya una implementación autorizada disponible. La activación y la reindexación son acciones locales del operador en esta etapa.

A dónde ir después

• Agentes — cómo un agente usa sesiones, reservas y puntos de control sobre estas herramientas.
• La CLI de AWR — las mismas operaciones de dominio desde la línea de comandos, para operadores y depuración.
• Solución de problemas — conflictos de revisión, fuentes obsoletas y recuperación.