Render Useful MCP

render-useful-mcp

Um servidor Model Context Protocol para Render que expõe todos os endpoints da API Pública oficial do Render, além de um punhado de ferramentas de nível mais alto para os fluxos de trabalho que a API bruta torna tediosos.

Escrito em TypeScript. Cada ferramenta de API é gerada a partir do próprio documento OpenAPI do Render, então a cobertura é completa por construção e permanece assim.

213 ferramentas: todas as 208 operações da API Pública do Render (versão do spec 1.0.0), mais 5 ferramentas de fluxo de trabalho para as sequências que a API bruta torna tediosas.

📖 Site de documentação · catálogo de ferramentas · llms.txt

---

Por que este

A maioria dos wrappers de API para em um subconjunto selecionado de endpoints, que fica desatualizado e deixa você travado no momento em que precisa de algo que o autor pulou.

• Completo, por construção. Cada operação no documento OpenAPI do próprio Render vira uma ferramenta. Tudo o que a API permite que sua chave faça é alcançável imediatamente — sem necessidade de opt-in.
• Utilizável por um modelo. Nomes são resolvidos para ids de forma difusa, seu workspace id é preenchido automaticamente, deploys podem ser aguardados em uma única chamada, e falhas retornam com uma dica em vez de um código de status puro.
• Redutível quando você quiser. Cada conjunto de ferramentas está ativado por padrão; RENDER_MCP_TOOLSETS e RENDER_MCP_READ_ONLY existem para restringir a superfície deliberadamente, não para bloqueá-la.
• Honesto sobre riscos. Anotações MCP destrutivas/somente leitura/idempotentes são derivadas de semânticas HTTP reais, para que clientes possam tomar decisões sensatas de aprovação automática — incluindo os PUTs que substituem uma coleção inteira, onde tudo o que o chamador omite é excluído. Segredos são mascarados nos logs.

Instalação

Ambos os botões pré-preenchem a configuração com uma chave de API de exemplo — substitua-a após a instalação.

Claude Code — instale globalmente, para que esteja presente em todos os projetos:

claude mcp add render --scope user -e RENDER_API_KEY=rnd_your_key -- npx -y render-useful-mcp

--scope user é a parte que importa. O Claude Code usa como padrão o escopo local, que registra o servidor apenas para o diretório atual — então funciona onde você instalou e está ausente em qualquer outro lugar, que é o motivo usual de um servidor recém-adicionado parecer desaparecer. Os três escopos são:

Escopo	Flag	Onde fica	Disponível em
Usuário (global)	--scope user	sua configuração de usuário	todos os projetos, todos os diretórios
Projeto	--scope project	.mcp.json, commitado	qualquer pessoa que fizer checkout do repositório
Local	nenhum (padrão)	estado de usuário por diretório	o diretório de onde foi adicionado

Confirme com claude mcp list, e execute novamente o comando com --scope user se render não estiver listado a partir de um diretório não relacionado.

Claude Code, como plugin — isso conecta o servidor e sua documentação em uma única etapa, e plugins são instalados globalmente por natureza:

/plugin marketplace add LuSrodri/render-useful-mcp
/plugin install render-useful-mcp@lusrodri-render

Exporte RENDER_API_KEY no shell que inicia o Claude Code; o plugin o lê do ambiente em vez de armazená-lo. Veja plugin/README.md.

Claude para macOS e Windows, como extensão de desktop — baixe o pacote .mcpb do último release e abra-o. O Claude o instala e solicita a chave de API em um formulário, então nada é configurado manualmente. O pacote inclui suas próprias dependências; não precisa de npm ou de uma instalação global do Node.

Instalações de desktop usam como padrão os conjuntos de ferramentas services, logs e env-groups em vez do catálogo inteiro, porque cada definição de ferramenta custa contexto em toda conversa. Defina o campo Toolsets como all, ou como qualquer lista separada por vírgulas, para mudar isso.

Requer Node.js ≥ 20.11 para todas as rotas de instalação, exceto a extensão de desktop.

npm install -g render-useful-mcp

Ou execute sem instalar, que é o que a maioria das configurações de clientes MCP faz:

npx -y render-useful-mcp

Também está listado no MCP Registry como io.github.LuSrodri/render-useful-mcp, então clientes que navegam pelo registro podem encontrá-lo e configurá-lo sem serem apontados para o pacote npm manualmente.

Configure seu cliente MCP

Obtenha uma chave de API em Render Dashboard → Account Settings → API Keys.

Claude Code — globalmente, como acima:

claude mcp add render --scope user -e RENDER_API_KEY=rnd_your_key -- npx -y render-useful-mcp

Adicione RENDER_WORKSPACE_ID da mesma forma se você souber:

claude mcp add render --scope user \
  -e RENDER_API_KEY=rnd_your_key \
  -e RENDER_WORKSPACE_ID=tea_your_workspace_id \
  -- npx -y render-useful-mcp

Claude Desktop / qualquer cliente usando mcpServers — adicione ao arquivo de configuração:

{
  "mcpServers": {
    "render": {
      "command": "npx",
      "args": ["-y", "render-useful-mcp"],
      "env": {
        "RENDER_API_KEY": "rnd_your_key_here",
        "RENDER_WORKSPACE_ID": "tea_your_workspace_id"
      }
    }
  }
}

RENDER_WORKSPACE_ID é opcional, mas recomendado: muitos endpoints do Render exigem um ownerId que o modelo não tem como adivinhar, e defini-lo remove uma consulta de quase todas as sessões. Encontre-o com a ferramenta render_list_owners, ou leia-o na URL do seu dashboard.

Configuração

Variável	Padrão	Descrição
RENDER_API_KEY	—	Obrigatória. Sua chave de API do Render.
RENDER_WORKSPACE_ID	—	Workspace id aplicado onde quer que um ownerId seja necessário e nenhum foi fornecido.
RENDER_MCP_TOOLSETS	all	Reduza a superfície para uma lista separada por vírgulas de conjuntos de ferramentas.
RENDER_MCP_READ_ONLY	false	Quando verdadeiro, apenas ferramentas não mutáveis (GET) são expostas.
RENDER_MCP_DYNAMIC_TOOLSETS	true	Registra render_toolsets, que relata os conjuntos de ferramentas e seu estado.
RENDER_MCP_TIMEOUT_MS	60000	Timeout por requisição.
RENDER_MCP_MAX_RETRIES	3	Tentativas para limites de taxa e erros transitórios do servidor.
RENDER_MCP_MAX_RESPONSE_BYTES	400000	Resultados de ferramentas maiores que isso são truncados com uma nota.
RENDER_MCP_LOG_LEVEL	info	debug, info, warn, error, silent. Logs vão para stderr.
RENDER_API_BASE_URL	https://api.render.com/v1	Substituição para proxies ou testes.

Conjuntos de ferramentas

Todos os 17 conjuntos de ferramentas estão habilitados por padrão

— o servidor expõe tudo o que sua chave de API tem permissão para alcançar. Conjuntos de ferramentas são uma forma de _reduzir_ a superfície propositalmente, não um portão que você precisa destravar.

Conjunto de ferramentas	Ferramentas	Cobre
services	43	Serviços, deploys, domínios personalizados, jobs avulsos, execuções de cron jobs e eventos
metrics	23	Métricas de CPU, memória, banda, HTTP, disco e conexão, além de streams de métricas
postgres	21	Instâncias Postgres, usuários, exportações, recuperação e insights de consultas
workflows	15	Render Workflows e tarefas de workflow
env-groups	13	Grupos de ambiente, suas variáveis e arquivos secretos
projects	12	Projetos e ambientes
webhooks	11	Webhooks e configurações/substituições de notificações
logs	10	Consultas de logs, descoberta de labels e configuração de streams de log
static-sites	9	Regras de cabeçalho e rotas de redirecionamento/reescrita para sites estáticos
deprecated	8	Endpoints Redis legados que o Render substituiu pela API Key Value
key-value	8	Instâncias Key Value (compatível com Redis) e informações de conexão
workspaces	8	Workspaces, membros, o usuário autenticado e logs de auditoria
disks	7	Discos persistentes e seus snapshots
blueprints	6	Blueprints e sincronizações de Blueprint
network	5	Conjuntos de IPs de saída dedicados
registry	5	Credenciais de registry de contêineres
maintenance	4	Execuções de manutenção agendadas

Motivos pelos quais você pode reduzi-lo mesmo assim:

// A client that struggles with the full catalogue, or a session scoped to one job.
"env": { "RENDER_MCP_TOOLSETS": "services,logs,metrics" }

// An agent that should be able to look but not touch.
"env": { "RENDER_MCP_READ_ONLY": "true" }

Se você reduzir, o modelo ainda pode chamar render_toolsets para ver tudo o que existe e quais grupos estão desligados, para que ele possa dizer exatamente o que mudar. Ampliar a superfície significa editar RENDER_MCP_TOOLSETS e reiniciar o servidor: a revisão do protocolo 2026-07-28 exige que o resultado de tools/list não varie por conexão ou como efeito colateral de outra chamada, então o conjunto habilitado é fixado na inicialização.

Ferramentas

Ferramentas de fluxo de trabalho

Elas estão sempre disponíveis, em qualquer configuração de conjunto de ferramentas. Elas existem porque a sequência bruta equivalente são várias chamadas que o modelo geralmente erra na primeira tentativa.

Ferramenta	O que faz
render_find_service	Resolve um nome de serviço — incluindo um parcial ou aproximado — para um único serviço do Render, retornando seu id além de alternativas próximas.
render_recent_logs	Busca linhas de log recentes para um serviço, resolvendo o nome do serviço e o workspace id para você.
render_service_status	Triagem em uma chamada para um serviço: sua configuração, deploys mais recentes, instâncias em execução e os logs de nível de erro mais recentes.
render_toolsets	Lista todos os conjuntos de ferramentas do Render com sua contagem de ferramentas e se está habilitado atualmente.
render_wait_for_deploy	Faz polling de um deploy até atingir um estado terminal (live, build_failed, update_failed, canceled, deactivated) ou o timeout expirar.

Ferramentas de API

Uma por endpoint do Render, nomeadas render_<operation_id> — render_list_services, render_create_deploy, render_update_postgres, e assim por diante. Cada uma carrega o resumo, a descrição, a documentação de parâmetros, enums e restrições diretamente do spec do Render. A lista completa está na página do catálogo de ferramentas.

Tornando as ferramentas utilizáveis por um modelo

Uma ferramenta gerada é tão boa quanto o que o spec diz sobre ela, e o spec do Render descreve formas em vez de uso. Três coisas fecham essa lacuna:

oneOf branches mantêm seus nomes e dizem qual se aplica. Desreferenciar um $ref normalmente descarta o nome do schema, o que deixa serviceDetails em render_create_service como cinco objetos anônimos estruturalmente semelhantes, sem nada que diga qual corresponde a qual type. Cada branch agora carrega seu nome do spec do Render como um title, então cron_job → cronJobDetailsPOST e runtime: docker → dockerDetails são decisões que um modelo pode realmente tomar. Nomear os branches torna a escolha legível, mas não verificável, e a especificação do Render não carrega discriminator: sob a regra de exatamente-um de oneOf, um branch que não exige nada — staticSiteDetailsPOST — aceita qualquer payload, o que deixa os outros quatro inalcançáveis. src/tools/schema-unions.ts reescreve essas uniões em regras de if/then baseadas na propriedade que as seleciona, então o mapeamento faz parte do schema em vez de ser uma recomendação na descrição, e um campo de branch errado é rejeitado pelo nome em vez de como must match exactly one schema in oneOf. Uma invariante de build falha o gerador se qualquer branch de oneOf ficar inalcançável, e test/payloads.test.ts verifica a propriedade contra payloads reais para todas as 208 ferramentas.

Campos que nenhum chamador pode preencher são removidos. A especificação do Render reutiliza schemas de resposta dentro de corpos de requisição em alguns lugares, o que arrasta valores que o servidor gera: o branch Docker de um cron job pede um objeto registryCredential inteiro exigindo o id da credencial e o timestamp da sua última alteração, enquanto um web service aceita um registryCredentialId simples. Um campo que só pode ser preenchido com valores inventados é pior do que nenhum campo, então src/tools/schema-repairs.ts o remove e a nota de uso aponta para image.registryCredentialId, que é onde o Render realmente aceita a referência. O gerador lança um erro se uma entrada deixar de corresponder, então uma correção upstream aparece como falha de build.

Algumas ferramentas carregam notas de uso escritas à mão. src/tools/operation-hints.ts acrescenta um parágrafo de Usage: às operações que os modelos demonstravelmente erram — create-service recebe exemplos completos e trabalhados, update-env-vars-for-service avisa que substitui o conjunto inteiro, post-job diz que não é assim que se cria um cron job. Exemplos são dados, não prosa: cada um é validado contra o schema da própria ferramenta pela suíte de testes e renderizado na descrição a partir do mesmo objeto, então um exemplo publicado é um que o servidor comprovadamente aceita. O gerador lança um erro se uma dica nomear uma operação que o Render retirou, então o arquivo não pode apodrecer silenciosamente.

O servidor envia instructions. src/instructions.ts é entregue uma vez em initialize: prefixos de id, resolva-o-nome-primeiro, qual ferramenta de workflow substitui qual sequência bruta, e a convenção de oneOf. Conselhos entre ferramentas pertencem a esse lugar em vez de serem duplicados em cada descrição de ferramenta que precise deles.

Criando um cron job que executa uma imagem Docker

O caso que motivou todos os três. Um cron job é um serviço, então:

// render_create_service
{
  "type": "cron_job",
  "name": "nightly-report",
  "ownerId": "tea-…",
  "repo": "https://github.com/acme/reports",
  "branch": "main",
  "serviceDetails": {
    // the cronJobDetailsPOST branch
    "runtime": "docker",
    "schedule": "0 3 * * *", // five-field cron, UTC, required for cron jobs
    "plan": "starter",
    "region": "oregon",
    "envSpecificDetails": {
      // the dockerDetails branch, because runtime is docker
      "dockerfilePath": "./Dockerfile",
      "dockerContext": ".",
      "dockerCommand": "python report.py",
    },
  },
}

Para uma imagem pré-construída em vez de um build, remova repo/branch, defina image como {"ownerId": "tea-…", "imagePath": "docker.io/acme/reports:latest"}, use "runtime": "image", e dê a envSpecificDetails apenas o dockerCommand. Mude o agendamento depois com render_update_service; dispare uma execução fora do agendamento com render_run_cron_job. render_create_job é uma coisa diferente — um comando único em um serviço existente.

Notas de design

Gerado, não escrito à mão. scripts/generate-operations.ts lê spec/render-openapi.json e emite o catálogo de ferramentas. É estrito: uma tag não mapeada, uma colisão de nomes, um $ref cíclico, um parâmetro de caminho ausente do seu template, ou uma propriedade de corpo que sombrearia um parâmetro de query — tudo isso falha o build em vez de produzir uma ferramenta sutilmente errada. Atualizar para uma nova versão da API do Render é: colocar a nova especificação, rodar npm run generate, revisar o diff.

Schemas chegam ao cliente intactos. A especificação do Render usa toda a gama de JSON Schema. Schemas de ferramentas são totalmente desreferenciados e passados adiante, e o Ajv valida argumentos contra eles — então enums, padrões, formatos e oneOf são todos realmente aplicados. É por isso que o servidor usa o Server de baixo nível do SDK em vez de McpServer, que aceita apenas schemas Zod. A única reescrita deliberada são as uniões não discriminadas descritas acima: deixadas como a especificação as escreve, elas não podem ser satisfeitas de forma alguma.

Corpos são achatados. Propriedades do corpo da requisição tornam-se argumentos de ferramenta de nível superior, o que mantém os pontos de chamada rasos e melhora a precisão das chamadas de ferramenta. O gerador prova em tempo de build que propriedades do corpo nunca colidem com parâmetros de caminho ou query. Os seis corpos com valores de array e oneOf mantêm sua estrutura sob um único argumento body.

Erros são tornados acionáveis. Uma falha retorna o status HTTP, a mensagem do próprio Render e uma dica apontando para a causa real — um 404 sugere confirmar o id com uma chamada de listagem, um 401 aponta para a página da chave de API. Uma ferramenta registrada mas oculta diz qual conjunto de ferramentas habilitar em vez de "ferramenta desconhecida".

Reintentos são conservadores. Limites de taxa e 5xx transitórios são repetidos com backoff de jitter descorrelacionado, respeitando Retry-After. Métodos não idempotentes nunca são repetidos em um erro de servidor: um POST /deploys repetido faria deploy duas vezes.

Segredos ficam fora dos logs. O registro é JSON estruturado em stderr — stdout é o transporte — com strings de conexão, chaves de API e tokens redigidos.

Desenvolvimento

npm install
npm run generate    # rebuild the tool catalogue from the OpenAPI spec
npm run docs        # re-render every doc that quotes the catalogue
npm run build
npm test
npm run check       # generate + docs + lint + typecheck + test

A documentação também é gerada

Contagens de ferramentas, a tabela de conjuntos de ferramentas, a lista de ferramentas de workflow, todo o site de docs, llms.txt e llms-full.txt são todos renderizados a partir de src/generated/operations.json por scripts/generate-docs.ts. Regiões entre marcadores <!-- generated:key --> neste arquivo e plugin/README.md são reescritas no lugar; os arquivos do site são escritos por inteiro.

npm run docs:check re-renderiza tudo e falha se diferir do que está commitado. CI o executa em cada pull request, o workflow Pages o executa antes de fazer deploy, e a sincronização da especificação executa npm run docs para que uma mudança de API e a prosa que a descreve cheguem em um único pull request revisável. Números na documentação não podem divergir silenciosamente do catálogo — o que acontecia, antes disso existir.

A suíte de testes cobre invariantes do catálogo (todas as 208 operações, sem $ref pendentes, parâmetros de caminho obrigatórios, anotações correspondendo à semântica HTTP), mapeamento de requisições, comportamento de reintento e paginação, as ferramentas compostas, e um round trip completo de cliente/servidor MCP em memória.

Construindo a extensão de desktop

npm run build:mcpb   # -> build/render-useful-mcp-<version>.mcpb

Isso prepara dist/ mais a árvore de dependências de produção em build/mcpb/ e o empacota. O bundle é autocontido por design — o Claude o executa sem etapa de instalação — então as dependências são copiadas do node_modules deste repositório em vez de reinstaladas, o que é o que garante que o artefato contém a árvore na qual a suíte de testes realmente rodou.

manifest.json na raiz do repositório é o manifesto da extensão; npm version mantém sua versão em sincronia com o pacote. Para inspecionar um bundle construído:

npx mcpb info build/render-useful-mcp-<version>.mcpb
npx mcpb unpack build/render-useful-mcp-<version>.mcpb /tmp/check

Atualizando para uma nova versão da API do Render

Isso é automatizado. .github/workflows/spec-sync.yml roda diariamente, busca a descrição atual da API do Render, regenera o catálogo e a documentação, e abre um pull request quando o conjunto de ferramentas realmente muda — com um resumo de quais ferramentas foram adicionadas, removidas ou tiveram a forma alterada, e um aviso quando a mudança é quebra de compatibilidade. Nada é mesclado automaticamente.

Cada execução escreve no resumo do job, incluindo as execuções que não encontram nada, então "verificou hoje?" é respondível na aba Actions em vez de ser inferido pela ausência de um pull request.

Dois detalhes do agendamento são deliberados, e ambos vêm do job parecer morto enquanto na verdade estava funcionando:

• 47 5 * * *, não 0 6 * * 1. O GitHub enfileira workflows agendados com melhor esforço e os descarta sob carga; o topo da hora é o slot mais disputado que existe. A única execução agendada observada começou quase quatro horas atrasada. Diariamente, em um minuto comum, faz uma execução descartada custar um dia em vez de duas semanas — e uma execução que não encontra mudança no catálogo sai cedo, então o custo de diário é alguns segundos de CI.
• .github/spec-sync-heartbeat.json. O GitHub desabilita workflows agendados em repositórios que ficam 60 dias sem atividade, e um workflow desabilitado não pode se reabilitar sozinho. O workflow commita um timestamp nesse arquivo sempre que o registrado tem mais de 20 dias — cerca de 18 commits por ano, o que mantém o relógio bem longe do limite e deixa um registro visível no git log de que a rotina está viva.

Para fazer manualmente, ou para verificar agora:

npm run sync-spec   # fetch the current spec into spec/render-openapi.json
npm run generate    # rebuild the catalogue from it
git diff src/generated/operations.json
npm test

O Render não serve seu documento OpenAPI de uma URL estável — os endpoints documentados .json e .yaml retornam 404 — então scripts/fetch-spec.ts o extrai do HTML da documentação. Isso é frágil por natureza, então valida o que extrai (título, servidor, contagem mínima de operações) e falha ruidosamente em vez de sobrescrever uma especificação boa com uma truncada. Se o Render mudar sua plataforma de documentação, o workflow de sincronização fica vermelho em vez de reportar silenciosamente "sem mudanças" para sempre.

O gerador se recusa a emitir um catálogo que não consegue entender completamente — uma tag não mapeada, uma colisão de nomes, um $ref cíclico, um parâmetro de caminho ausente do seu template, ou uma propriedade de corpo que sombrearia um parâmetro de query — tudo isso falha o build. CI adicionalmente afirma que o catálogo commitado corresponde ao que a especificação produz, então uma atualização de especificação sem regeneração não pode ser mesclada.

Lançando versões

Um lançamento publica em dois lugares: o pacote no npm, e metadados descrevendo-o no MCP Registry. Ambos autenticam com o token OIDC do GitHub do workflow — npm via Trusted Publishing, o registry via mcp-publisher login github-oidc — então nenhum token npm ou segredo de registry é armazenado em qualquer lugar. A publicação npm carrega uma atestação de proveniência.

npm version patch    # or minor / major
git push --follow-tags

Enviar uma tag v* executa .github/workflows/publish.yml, que verifica se a tag corresponde a package.json e se o catálogo gerado e a documentação estão atualizados, descobre qual dos dois alvos ainda precisa desta versão, então faz lint, type-check, testes, build e publica. Também constrói o bundle .mcpb e o anexa ao GitHub Release, que é o único lugar de onde a extensão de desktop é distribuída.

A verificação de documentação é repetida aqui em vez de deixada para o CI porque README.md viaja dentro do tarball npm e uma tag pode ser cortada de qualquer commit. Versões npm são imutáveis, então um pacote cujo README contradiz o catálogo ao lado dele não pode ser retirado.

A ordem é fixa: npm primeiro, depois o registry. O registry prova que você é dono do pacote buscando o tarball publicado e procurando por mcpName em seu package.json, então não pode aceitar uma versão que o npm ainda não serviu.

Se um lançamento falhar por um motivo fora do código, execute-o novamente na aba Actions via Run workflow, selecionando a tag em Use workflow from. Cada alvo é verificado independentemente, então um reintento após um lançamento meio terminado pula o que já teve sucesso em vez de falhar nas versões imutáveis do npm. O workflow rejeita disparos de um branch, então uma versão publicada sempre corresponde a uma tag.

O manifesto do registry

server.json é a cópia do registry dos metadados deste servidor. Dois de seus campos são críticos e ambos são verificados por test/server-json.test.ts:

• name deve ser io.github.LuSrodri/.... O registry deriva o namespace no qual você pode publicar da claim repository_owner do token OIDC e o compara com sensibilidade a maiúsculas/minúsculas, então a grafia em minúsculas é rejeitada com um 403.
• mcpName em package.json deve ser igual a esse mesmo nome. É a prova de propriedade descrita acima; sem ela o registry recusa o pacote.

Os campos de versão acompanham package.json — npm version os mantém em sincronia via script de ciclo de vida version, então mcp-publisher publish também funciona a partir de um checkout local limpo. CI os carimba a partir da tag novamente antes de publicar, então a tag é o que decide o que é enviado.

Privacidade

Sem telemetria, sem analytics, sem backend. O servidor roda na sua máquina e contata exatamente um host — a API da Render. Sua chave é lida do ambiente, enviada apenas para a Render, nunca gravada em disco e ocultada na saída de logs. Detalhes completos, incluindo como verificar cada afirmação você mesmo: PRIVACY.md.

Licença

MIT — veja LICENSE.

Não afiliado à Render. spec/render-openapi.json é a descrição publicada da API da Render, incluída para que os builds sejam reproduzíveis.