Patchrooms

Patchrooms expone un endpoint de Model Context Protocol para que un agente de IA (Claude, Cursor y otros) pueda listar, leer, archivar y clasificar los informes de comentarios de un proyecto. Son los mismos datos que ves en el panel, servidos como JSON-RPC a través de un único endpoint HTTP.

Endpoint

POST https://room.patchrooms.com/mcp

El endpoint habla JSON-RPC 2.0. Envía method, params y un id en el cuerpo de la solicitud; la respuesta hace eco del id.

Autenticación

Dos formas de acceso, y el proyecto se resuelve a partir de la credencial en ambos casos — no hay id de proyecto en la URL.

OAuth (predeterminado). Un cliente interactivo se autoriza en el navegador: lee los metadatos OAuth del endpoint, abre una página de consentimiento de Patchrooms y almacena el token resultante por sí mismo. Nada secreto termina en tu configuración. Consulta Conectar un agente de codificación.

Clave de API (sin interfaz). Una ejecución desatendida envía una clave secreta (prefijo pr_sk_) creada en el panel, como token Bearer:

Authorization: Bearer pr_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

En cualquier caso, la concesión debe llevar el alcance feedback:read para list_reports / get_report, o el endpoint devuelve 403. set_status además requiere feedback:write.

Crear una clave (solo sin interfaz)

Omite esto si tu cliente puede abrir un navegador — OAuth lo cubre. Para CI y otras ejecuciones desatendidas, abre el proyecto → Integraciones → Claves de API → Crear en el panel y elige los alcances que el agente necesite:

• feedback:read — list_reports, get_report, list_projects, list_channels.
• feedback:write — además permite create_report, create_room, set_status, add_comment.
• channel:read / channel:write — leer o gestionar canales (API REST).
• project:read / project:write — leer o configurar el proyecto (API REST).
• apikey:write — emitir y revocar claves (API REST).
• * — comodín, satisface cualquier alcance. Reservado para tokens de configuración de corta duración emitidos en el panel; no se puede emitir a través de la propia API.

El valor de pr_sk_… se muestra solo una vez al crearlo. Guárdalo en una variable de entorno (p. ej. PATCHROOMS_API_KEY) o en el almacén de credenciales de tu agente. Las claves pueden llevar un TTL opcional — utilizado para tokens de configuración, que caducan y se revocan después del aprovisionamiento (consulta Autoconfiguración del agente).

Conectar un agente de codificación

Nada que pegar, ninguna clave que gestionar: apunta el cliente a la URL y autoriza en el navegador. El endpoint anuncia sus metadatos OAuth, por lo que el cliente descubre el resto por sí mismo.

Claude Code — registra el servidor (el alcance del proyecto escribe .mcp.json):

claude mcp add --transport http patchrooms https://room.patchrooms.com/mcp --scope project

La primera llamada a una herramienta abre la página de consentimiento de Patchrooms: inicia sesión, elige qué compartir — un solo proyecto o Todos los proyectos de una organización — además del nivel de acceso (solo lectura, o lectura + clasificación), y autoriza. /mcp en Claude Code muestra el estado de la conexión y puede volver a ejecutar el flujo.

El .mcp.json resultante no contiene nada secreto, por lo que es seguro confirmarlo:

{
  "mcpServers": {
    "patchrooms": {
      "type": "http",
      "url": "https://room.patchrooms.com/mcp"
    }
  }
}

Cursor, Windsurf, los conectores de claude.ai y otros clientes MCP usan la misma URL sin cabecera.

En el primer uso, llama a introduce con el nombre de tu agente (y el propietario, si se conoce) — es una llamada de una línea y cada informe que archives o veas después llevará ese nombre en lugar del nombre de la concesión en bruto.

Sin interfaz: conectar con una clave de API

Una ejecución desatendida (CI, un trabajo cron, un contenedor sin navegador) no puede completar una pantalla de consentimiento. Esas se autentican con una clave pr_sk_… como cabecera Bearer, leída del entorno — nunca codificada, nunca confirmada:

claude mcp add --transport http patchrooms https://room.patchrooms.com/mcp \
  --header "Authorization: Bearer $PATCHROOMS_API_KEY" --scope project

{
  "mcpServers": {
    "patchrooms": {
      "type": "http",
      "url": "https://room.patchrooms.com/mcp",
      "headers": { "Authorization": "Bearer ${PATCHROOMS_API_KEY}" }
    }
  }
}

${PATCHROOMS_API_KEY} se expande desde el shell que lanzó el cliente, así que expórtala antes de iniciar una sesión.

¿Sin cliente MCP? El POST JSON-RPC tools/call que se muestra a continuación funciona desde curl o cualquier script — lee la clave del entorno y golpea el endpoint directamente.

Conectar claude.ai / Cowork

Mismo flujo OAuth, añadido desde la interfaz en lugar de un CLI:

Configuración → Conectores → Añadir conector personalizado → https://room.patchrooms.com/mcp

Claude descubre los endpoints OAuth automáticamente y abre la página de consentimiento de Patchrooms. Los conectores personalizados en claude.ai no pueden enviar una cabecera personalizada en absoluto, por lo que esta es la única vía de acceso allí — y no necesita clave de API.

Con una concesión a nivel de organización, list_reports abarca todos los proyectos de la organización (cada elemento lleva un nombre de project), y get_report / set_status aceptan informes de cualquiera de ellos. Las claves a nivel de organización funcionan en el endpoint MCP; la API REST aún requiere una clave por proyecto.

Detrás de escena, se emite una clave de API dedicada llamada OAuth: <client> para el conector, con el alcance exacto de lo que elegiste. Aparece en Integraciones → Claves de API como cualquier otra clave — revócala allí en cualquier momento para desconectar el cliente. Reconectar el conector simplemente recorre el mismo flujo y emite una clave nueva.

Cualquier otro cliente MCP compatible con OAuth (MCP Inspector y otros) se conecta de la misma manera: apúntalo a la URL del endpoint y recorrerá el mismo flujo.

Herramientas

El servidor anuncia nueve herramientas a través de tools/list.

introduce

Presenta al agente que llama — llámala una vez, antes de las otras herramientas. Etiqueta la clave de API para que los informes que el agente archiva o lee se le atribuyan por nombre, en lugar del nombre de la clave en bruto.

Argumento	Tipo	Descripción
agentName	string	Obligatorio. Cómo etiquetar a este agente, p. ej. "Claude (health-os)".
owner	string	A quién pertenece este agente, p. ej. un nombre de usuario o de equipo.

Opcional — nada bloquea las otras herramientas si la omites, pero los informes y las vistas recurren al nombre propio de la clave de API en lugar de una etiqueta elegida por el agente.

list_reports

Lista los informes de comentarios del proyecto, primero los más recientes, en forma compacta. Cada informe devuelto se marca como visto por el agente que llama (de tipo disparar y olvidar, nunca bloquea la respuesta) — consulta Seguimiento de lectura.

Argumento	Tipo	Descripción
status	string	Filtrar por estado del informe.
channelKey	string	Filtrar por clave de canal.
artifactId	string	Filtrar por id de artefacto.
q	string	Búsqueda de subcadena sin distinguir mayúsculas en el texto del informe (bloques de texto/selección y transcripciones de audio).
url	string	Filtrar a informes cuya URL de página contenga esta subcadena.
since	string	Fecha/fecha-hora ISO — solo informes creados después de esto.
limit	number	Máximo de resultados. El valor predeterminado es 50, con un tope de 200.

Todos los argumentos son opcionales.

get_report

Devuelve un solo informe renderizado como Markdown, con sus capturas de pantalla incrustadas como contenido de imagen que el agente puede ver directamente — hasta 6 imágenes, con un tope de 8 MB en total, sin paso de descarga separado. Marca el informe como visto por el agente que llama, igual que list_reports.

Argumento	Tipo	Descripción
id	string	Id del informe. Obligatorio.

list_projects

Lista los proyectos sobre los que esta clave de API puede actuar — llámala antes de pasar project a create_report, create_room o list_channels. Una clave con alcance de proyecto siempre devuelve solo su propio proyecto; una clave a nivel de organización devuelve todos los proyectos de su organización.

Sin argumentos. Devuelve un array JSON compacto de { id, name, projectKey, slug, defaultChannelKey }.

list_channels

Lista los canales de un proyecto — llámala antes de pasar channelKey a create_report.

Argumento	Tipo	Descripción
project	string	Id de proyecto, clave, slug o nombre. Obligatorio para claves a nivel de organización, omítelo para claves con alcance de proyecto.

Devuelve un array JSON compacto de { key, name }.

create_report

Archiva un nuevo informe de comentarios — para agentes que detectan problemas por sí mismos (una verificación fallida, un widget roto, un defecto de API). El informe se marca como enviado a través de MCP (context.extra.via = 'mcp'). Requiere el alcance feedback:write.

Argumento	Tipo	Descripción
message	string	Cuerpo del informe, texto plano o Markdown. Obligatorio.
channelKey	string	Clave de canal. El valor predeterminado es el canal predeterminado del proyecto.
url	string	Página o recurso sobre el que trata el informe.
author	string	Nota de forma libre sobre quién archiva esto, almacenada en context.extra. No afecta al autor estructurado del informe — ese es siempre agent:<key>, etiquetado desde introduce.
project	string	Id de proyecto, clave, slug o nombre. Obligatorio para claves a nivel de organización.

create_room

Inicia (o reanuda) una sala para un artefacto/tarea en la que estás trabajando — actualización idempotente por artifact_id, segura de llamar cada vez que comiences el trabajo, antes de que exista cualquier informe. El resultado incluye un url que apunta a la sala en el panel, listo para entregar a un humano. Requiere el alcance feedback:write.

Argumento	Tipo	Descripción
artifact_id	string	Obligatorio. Id estable para el artefacto/tarea — los informes y las futuras llamadas a create_room se agrupan bajo esto.
title	string	Título de sala legible por humanos.
goal	string	Lo que intentas lograr en esta sala.
project	string	Id de proyecto, clave, slug o nombre. Obligatorio para claves a nivel de organización.

set_status

Clasifica un informe estableciendo su estado. Requiere el alcance feedback:write.

Argumento	Tipo	Descripción
id	string	Id del informe. Obligatorio.
status	string	Uno de new, triaged, in-progress, fixed, verified, canceled. Obligatorio.

Establece fixed una vez que se haga el cambio; verified significa que un humano confirmó que funciona, así que déjalo a ellos a menos que se te pida lo contrario.

add_comment

Responde en el hilo de comentarios de un informe — actualizaciones de progreso, preguntas o una explicación de una corrección en un informe en el que el agente ya está trabajando. Requiere el alcance feedback:write.

Los comentarios llegan como borradores de forma predeterminada. Un borrador es visible solo en el panel, donde un humano lo lee y lo publica como el agente, edita el texto primero o lo publica bajo su propio nombre. Nada llega al hilo hasta que ellos lo hagan. Pasa draft: false para publicar directamente en el hilo — apropiado en un bucle desatendido sin paso de revisión humana, o cuando la persona lo pidió explícitamente.

Argumento	Tipo	Descripción
report_id	string	Id del informe. Obligatorio.
text	string	Cuerpo del comentario, texto plano o Markdown. Obligatorio.
draft	boolean	El valor predeterminado es true (mantener para aprobación humana). false publica inmediatamente.
kind	string	Etiqueta opcional para clasificación: fix, question, options, deferral, techdebt.

kind es lo que hace que un lote de respuestas sea escaneable — un humano puede filtrar a cada question que bloquea al agente en lugar de leer cada comentario. Usa fix para un cambio ya realizado, question cuando se necesita una respuesta para continuar, options al presentar alternativas con compensaciones, deferral al proponer posponer con una razón, techdebt al explicar por qué algo es costoso debido a deuda existente.

Ejemplo

Lista los informes más recientes:

curl -s https://room.patchrooms.com/mcp \
  -H "Authorization: Bearer pr_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_reports",
      "arguments": { "limit": 2 }
    }
  }'

El resultado es un sobre de llamada a herramienta cuyo contenido de texto es un array JSON de informes:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  {\n    \"id\": \"665f1a2b3c4d5e6f7a8b9c0d\",\n    \"shortId\": \"9c0d\",\n    \"title\": \"Checkout button misaligned on mobile\",\n    \"status\": \"open\",\n    \"channelKey\": \"bug\",\n    \"url\": \"https://app.example.com/checkout\",\n    \"artifactId\": null,\n    \"createdAt\": \"2026-06-03T09:14:22.000Z\"\n  }\n]"
      }
    ]
  }
}

Obtén un informe como Markdown:

curl -s https://room.patchrooms.com/mcp \
  -H "Authorization: Bearer pr_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_report",
      "arguments": { "id": "665f1a2b3c4d5e6f7a8b9c0d" }
    }
  }'

El contenido del resultado es el informe renderizado como una cadena Markdown. Un id de informe que sea malformado, o que no pertenezca a tu proyecto, devuelve un resultado de herramienta con isError: true.

Notas del protocolo

• initialize devuelve la versión del protocolo 2024-11-05 y anuncia soporte de herramientas.
• tools/list devuelve las nueve herramientas mencionadas anteriormente.
• tools/call ejecuta una herramienta. Una herramienta o método desconocido devuelve un error JSON-RPC con el código -32601.