Patchrooms

Patchrooms expõe um endpoint de Model Context Protocol para que um agente de IA (Claude, Cursor e outros) possa listar, ler, registrar e triar os relatórios de feedback de um projeto. São os mesmos dados que você vê no dashboard, servidos como JSON-RPC em um único endpoint HTTP.

Endpoint

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

O endpoint fala JSON-RPC 2.0. Envie method, params e um id no corpo da requisição; a resposta ecoa o id.

Autenticação

Duas formas de acesso, e o projeto é resolvido a partir da credencial em ambos os casos — não há id de projeto na URL.

OAuth (padrão). Um cliente interativo autoriza no navegador: ele lê os metadados OAuth do endpoint, abre uma página de consentimento do Patchrooms e armazena o token resultante por conta própria. Nada secreto acaba na sua configuração. Veja Conectar um agente de codificação.

Chave de API (headless). Uma execução não supervisionada envia uma chave secreta (prefixo pr_sk_) criada no dashboard, como token Bearer:

Authorization: Bearer pr_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

De qualquer forma, a concessão deve carregar o escopo feedback:read para list_reports / get_report, ou o endpoint retorna 403. set_status adicionalmente exige feedback:write.

Criar uma chave (somente headless)

Pule isto se o seu cliente puder abrir um navegador — o OAuth cobre isso. Para CI e outras execuções não supervisionadas, abra o projeto → Integrações → Chaves de API → Criar no dashboard e escolha os escopos que o agente precisa:

• feedback:read — list_reports, get_report, list_projects, list_channels.
• feedback:write — adicionalmente permite create_report, create_room, set_status, add_comment.
• channel:read / channel:write — ler ou gerenciar canais (API REST).
• project:read / project:write — ler ou configurar o projeto (API REST).
• apikey:write — emitir e revogar chaves (API REST).
• * — curinga, satisfaz qualquer escopo. Reservado para tokens de configuração de curta duração emitidos no dashboard; não pode ser emitido via API em si.

O valor pr_sk_… é mostrado apenas uma vez na criação. Armazene-o em uma variável de ambiente (ex.: PATCHROOMS_API_KEY) ou no armazenamento de credenciais do seu agente. As chaves podem ter um TTL opcional — usado para tokens de configuração, que expiram e são revogados após o provisionamento (veja Autoconfiguração do agente).

Conectar um agente de codificação

Nada para colar, nenhuma chave para gerenciar: aponte o cliente para a URL e autorize no navegador. O endpoint anuncia seus metadados OAuth, então o cliente descobre o resto por conta própria.

Claude Code — registre o servidor (escopo do projeto grava .mcp.json):

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

A primeira chamada de ferramenta abre a página de consentimento do Patchrooms: faça login, escolha o que compartilhar — um único projeto ou Todos os projetos de uma organização — além do nível de acesso (somente leitura, ou leitura + triagem), e autorize. /mcp no Claude Code mostra o estado da conexão e pode reexecutar o fluxo.

O .mcp.json resultante não contém nada secreto, então é seguro fazer commit:

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

Cursor, Windsurf, conectores do claude.ai e outros clientes MCP usam a mesma URL sem cabeçalho.

No primeiro uso, chame introduce com o nome do seu agente (e proprietário, se conhecido) — é uma chamada de uma linha e todo relatório que você registrar ou visualizar depois carregará esse nome em vez do nome bruto da concessão.

Headless: conectar com uma chave de API

Uma execução não supervisionada (CI, um cron job, um contêiner sem navegador) não consegue concluir uma tela de consentimento. Esses autenticam com uma chave pr_sk_… como cabeçalho Bearer, lida do ambiente — nunca codificada, nunca commitada:

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} é expandido a partir do shell que iniciou o cliente, então exporte-o antes de iniciar uma sessão.

Sem cliente MCP? O POST JSON-RPC tools/call mostrado abaixo funciona a partir de curl ou qualquer script — leia a chave do ambiente e acesse o endpoint diretamente.

Conectar claude.ai / Cowork

Mesmo fluxo OAuth, adicionado pela interface em vez de um CLI:

Configurações → Conectores → Adicionar conector personalizado → https://room.patchrooms.com/mcp

O Claude descobre os endpoints OAuth automaticamente e abre a página de consentimento do Patchrooms. Conectores personalizados no claude.ai não podem enviar um cabeçalho personalizado, então esta é a única forma de acesso lá — e não precisa de chave de API.

Com uma concessão de nível organizacional, list_reports abrange todos os projetos da organização (cada item carrega um nome project), e get_report / set_status aceitam relatórios de qualquer um deles. Chaves de nível organizacional funcionam no endpoint MCP; a API REST ainda exige uma chave por projeto.

Nos bastidores, uma chave de API dedicada chamada OAuth: <client> é emitida para o conector, com escopo exatamente no que você escolheu. Ela aparece em Integrações → Chaves de API como qualquer outra chave — revogue-a lá a qualquer momento para desconectar o cliente. Reconectar o conector apenas percorre o mesmo fluxo e emite uma nova chave.

Qualquer outro cliente MCP com suporte a OAuth (MCP Inspector e outros) conecta da mesma forma: aponte-o para a URL do endpoint e ele percorrerá o mesmo fluxo.

Ferramentas

O servidor anuncia nove ferramentas via tools/list.

introduce

Apresenta o agente chamador — chame esta uma vez, antes das outras ferramentas. Ela rotula a chave de API para que os relatórios que o agente registra ou lê sejam atribuídos a ele pelo nome, em vez do nome bruto da chave.

Argumento	Tipo	Descrição
agentName	string	Obrigatório. Como rotular este agente, ex.: "Claude (health-os)".
owner	string	A quem este agente pertence, ex.: um nome de usuário ou equipe.

Opcional — nada bloqueia as outras ferramentas se você pular, mas relatórios e visualizações voltam ao nome da própria chave de API em vez de um rótulo escolhido pelo agente.

list_reports

Lista relatórios de feedback do projeto, do mais recente ao mais antigo, em formato compacto. Todo relatório retornado é marcado como visualizado pelo agente chamador (fire-and-forget, nunca bloqueia a resposta) — veja Rastreamento de leitura.

Argumento	Tipo	Descrição
status	string	Filtrar por status do relatório.
channelKey	string	Filtrar por chave de canal.
artifactId	string	Filtrar por id de artefato.
q	string	Busca de substring sem diferenciar maiúsculas/minúsculas no texto do relatório (blocos de texto/seleção e transcrições de áudio).
url	string	Filtrar para relatórios cuja URL de página contém esta substring.
since	string	Data/data-hora ISO — apenas relatórios criados após isso.
limit	number	Máximo de resultados. Padrão 50, limite de 200.

Todos os argumentos são opcionais.

get_report

Retorna um único relatório renderizado como Markdown, com suas capturas de tela embutidas como conteúdo de imagem que o agente pode olhar diretamente — até 6 imagens, limitadas a 8 MB no total, sem etapa separada de download. Marca o relatório como visualizado pelo agente chamador, igual ao list_reports.

Argumento	Tipo	Descrição
id	string	Id do relatório. Obrigatório.

list_projects

Lista os projetos nos quais esta chave de API pode atuar — chame antes de passar project para create_report, create_room ou list_channels. Uma chave com escopo de projeto sempre retorna apenas seu próprio projeto; uma chave de nível organizacional retorna todos os projetos da organização.

Sem argumentos. Retorna um array JSON compacto de { id, name, projectKey, slug, defaultChannelKey }.

list_channels

Lista os canais de um projeto — chame antes de passar channelKey para create_report.

Argumento	Tipo	Descrição
project	string	Id do projeto, chave, slug ou nome. Obrigatório para chaves de nível organizacional, omita para chaves com escopo de projeto.

Retorna um array JSON compacto de { key, name }.

create_report

Registra um novo relatório de feedback — para agentes que identificam problemas por conta própria (uma verificação falha, um widget quebrado, um defeito de API). O relatório é marcado como enviado via MCP (context.extra.via = 'mcp'). Exige o escopo feedback:write.

Argumento	Tipo	Descrição
message	string	Corpo do relatório, texto simples ou Markdown. Obrigatório.
channelKey	string	Chave do canal. Padrão: canal padrão do projeto.
url	string	Página ou recurso sobre o qual o relatório trata.
author	string	Nota livre sobre quem está registrando, armazenada em context.extra. Não afeta o autor estruturado do relatório — que é sempre agent:<key>, rotulado a partir de introduce.
project	string	Id do projeto, chave, slug ou nome. Obrigatório para chaves de nível organizacional.

create_room

Inicia (ou retoma) uma sala para um artefato/tarefa em que você está trabalhando — upsert idempotente por artifact_id, seguro chamar toda vez que você começar o trabalho, antes de existir qualquer relatório. O resultado inclui um url apontando para a sala no dashboard, pronto para entregar a um humano. Exige o escopo feedback:write.

Argumento	Tipo	Descrição
artifact_id	string	Obrigatório. Id estável para o artefato/tarefa — relatórios e futuras chamadas create_room agrupam-se sob este.
title	string	Título legível da sala.
goal	string	O que você está tentando realizar nesta sala.
project	string	Id do projeto, chave, slug ou nome. Obrigatório para chaves de nível organizacional.

set_status

Tria um relatório definindo seu status. Exige o escopo feedback:write.

Argumento	Tipo	Descrição
id	string	Id do relatório. Obrigatório.
status	string	Um de new, triaged, in-progress, fixed, verified, canceled. Obrigatório.

Defina fixed assim que a mudança for feita; verified significa que um humano confirmou que funciona, então deixe esse para eles, a menos que peçam o contrário.

add_comment

Responde no tópico de comentários de um relatório — atualizações de progresso, perguntas ou uma explicação de uma correção em um relatório no qual o agente já está trabalhando. Exige o escopo feedback:write.

Comentários chegam como rascunhos por padrão. Um rascunho é visível apenas no dashboard, onde um humano o lê e publica como o agente, edita o texto primeiro ou publica sob o próprio nome. Nada chega ao tópico até que isso aconteça. Passe draft: false para publicar direto no tópico — apropriado em um loop não supervisionado sem etapa de revisão humana, ou quando a pessoa pediu explicitamente.

Argumento	Tipo	Descrição
report_id	string	Id do relatório. Obrigatório.
text	string	Corpo do comentário, texto simples ou Markdown. Obrigatório.
draft	boolean	Padrão: true (segurar para aprovação humana). false publica imediatamente.
kind	string	Rótulo opcional para triagem: fix, question, options, deferral, techdebt.

kind é o que torna um lote de respostas escaneável — um humano pode filtrar para cada question bloqueando o agente em vez de ler cada comentário. Use fix para uma mudança já feita, question quando uma resposta for necessária para prosseguir, options ao apresentar alternativas com tradeoffs, deferral ao propor adiar com um motivo, techdebt ao explicar por que algo é caro devido a dívida existente.

Exemplo

Liste os relatórios mais recentes:

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 }
    }
  }'

O resultado é um envelope de chamada de ferramenta cujo conteúdo de texto é um array JSON de relatórios:

{
  "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]"
      }
    ]
  }
}

Busque um relatório 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" }
    }
  }'

O conteúdo do resultado é o relatório renderizado como uma string Markdown. Um id de relatório malformado, ou que não pertença ao seu projeto, retorna um resultado de ferramenta com isError: true.

Notas do protocolo

• initialize retorna a versão do protocolo 2024-11-05 e anuncia suporte a ferramentas.
• tools/list retorna as nove ferramentas acima.
• tools/call executa uma ferramenta. Uma ferramenta ou método desconhecido retorna um erro JSON-RPC com código -32601.