render-useful-mcp

A Model Context Protocol server for Render that exposes all 207 endpoints of the official Render Public API, plus a handful of higher-level tools for the workflows the raw API makes tedious.

Written in TypeScript. Every API tool is generated from Render's own OpenAPI document, so coverage is complete by construction and stays that way.

Why this one

Most API wrappers stop at a curated subset of endpoints, which drifts out of date and leaves you stuck the moment you need something the author skipped.

• Complete, by construction. All 207 operations, generated from Render's own OpenAPI document. Everything the API allows your key to do is reachable out of the box — no opt-in required.
• Usable by a model. Names resolve to ids fuzzily, your workspace id is filled in automatically, deploys can be waited on in one call, and failures come back with a hint instead of a bare status code.
• Narrowable when you want it. The 17 toolsets are all on by default; RENDER_MCP_TOOLSETS and RENDER_MCP_READ_ONLY exist to restrict the surface deliberately, not to gate it.
• Honest about risk. MCP destructive/read-only/idempotent annotations are derived from real HTTP semantics, so clients can make sensible auto-approval decisions. Secrets are redacted from logs.

Install

Requires Node.js ≥ 20.11.

npm install -g render-useful-mcp

Or run it without installing, which is what most MCP client configs do:

npx -y render-useful-mcp

It is also listed in the MCP Registry as io.github.LuSrodri/render-useful-mcp, so clients that browse the registry can find and configure it without being pointed at the npm package by hand.

Configure your MCP client

Get an API key from Render Dashboard → Account Settings → API Keys.

Claude Code

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

Claude Desktop / any client using mcpServers — add to the config file:

{
  "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 is optional but recommended: many Render endpoints require an ownerId that the model has no way to guess, and setting it removes a lookup from nearly every session. Find it with the render_list_owners tool, or read it from your dashboard URL.

Configuration

Toolsets

All 17 toolsets are enabled by default — the server exposes everything your API key is allowed to reach. Toolsets are a way to narrow the surface on purpose, not a gate you have to unlock.

Reasons you might narrow it anyway:

// A client that struggles with 212 tools, 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" }

If you do narrow it, the model can still call render_toolsets to see what exists and re-enable a group. The server emits notifications/tools/list_changed and the new tools appear immediately — no restart.

Tools

Workflow tools

These are always available, in any toolset configuration. They exist because the equivalent raw sequence is several calls the model usually gets wrong on the first try.

API tools

One per Render endpoint, named render_<operation_id> — render_list_services, render_create_deploy, render_update_postgres, and so on. Each carries the summary, description, parameter docs, enums and constraints straight from Render's spec.

Design notes

Generated, not hand-written. scripts/generate-operations.ts reads spec/render-openapi.json and emits the tool catalogue. It is strict: an unmapped tag, a name collision, a cyclic $ref, a path parameter missing from its template, or a body property that would shadow a query parameter all fail the build rather than producing a subtly wrong tool. Updating to a new Render API version is: drop in the new spec, run npm run generate, review the diff.

Schemas reach the client intact. Render's spec uses the full range of JSON Schema. Tool schemas are fully dereferenced and passed through unmodified, and Ajv validates arguments against them — so enums, patterns, formats and oneOf are all actually enforced. This is why the server uses the SDK's low-level Server rather than McpServer, which accepts only Zod schemas.

Bodies are flattened. Request-body properties become top-level tool arguments, which keeps call sites shallow and improves tool-call accuracy. The generator proves at build time that body properties never collide with path or query parameters. The six array- and oneOf-valued bodies keep their structure under a single body argument.

Errors are made actionable. A failure returns the HTTP status, Render's own message and a hint aimed at the actual cause — a 404 suggests confirming the id with a list call, a 401 points at the API key page. A tool that is registered but hidden says which toolset to enable rather than "unknown tool".

Retries are conservative. Rate limits and transient 5xx are retried with decorrelated-jitter backoff, honouring Retry-After. Non-idempotent methods are never replayed on a server error: a retried POST /deploys would deploy twice.

Secrets stay out of logs. Logging is structured JSON on stderr — stdout is the transport — with connection strings, API keys and tokens redacted.

Development

npm install
npm run generate    # rebuild the tool catalogue from the OpenAPI spec
npm run build
npm test
npm run check       # generate + lint + typecheck + test

The test suite covers catalogue invariants (all 207 operations, no dangling $ref, path params required, annotations match HTTP semantics), request mapping, retry and pagination behaviour, the composite tools, and a full in-memory MCP client/server round trip.

Updating to a new Render API version

This is automated. .github/workflows/spec-sync.yml runs weekly, fetches Render's current API description, regenerates the catalogue, and opens a pull request when the set of tools actually changes — with a summary of which tools were added, removed or changed shape, and a warning when the change is breaking. Nothing merges automatically.

To do it by hand, or to check right now:

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

Render does not serve its OpenAPI document from a stable URL — the documented .json and .yaml endpoints 404 — so scripts/fetch-spec.ts extracts it from the docs HTML. That is fragile by nature, so it validates what it extracts (title, server, minimum operation count) and fails loudly rather than overwriting a good spec with a truncated one. If Render changes their docs platform, the sync workflow goes red instead of quietly reporting "no changes" forever.

The generator refuses to emit a catalogue it cannot fully understand — an unmapped tag, a name collision, a cyclic $ref, a path parameter missing from its template, or a body property that would shadow a query parameter all fail the build. CI additionally asserts that the committed catalogue matches what the spec produces, so a spec update without a regenerate cannot merge.

Releasing

A release publishes to two places: the package to npm, and metadata describing it to the MCP Registry. Both authenticate with the workflow's GitHub OIDC token — npm via Trusted Publishing, the registry via mcp-publisher login github-oidc — so no npm token or registry secret is stored anywhere. The npm publish carries a provenance attestation.

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

Pushing a v* tag runs .github/workflows/publish.yml, which verifies the tag matches package.json and that the generated catalogue is current, works out which of the two targets still need this version, then lints, type-checks, tests, builds and publishes.

The order is fixed: npm first, then the registry. The registry proves you own the package by fetching the published tarball and looking for mcpName in its package.json, so it cannot accept a version npm has not served yet.

If a release fails for a reason outside the code, re-run it from the Actions tab via Run workflow, selecting the tag under Use workflow from. Each target is checked independently, so a retry after a half-finished release skips whatever already succeeded instead of failing on npm's immutable versions. The workflow rejects dispatches from a branch, so a published version always corresponds to a tag.

The registry manifest

server.json is the registry's copy of this server's metadata. Two of its fields are load bearing and both are asserted by test/server-json.test.ts:

• name must be io.github.LuSrodri/.... The registry derives the namespace you may publish to from the OIDC token's repository_owner claim and compares it case sensitively, so the lowercased spelling is rejected with a 403.
• mcpName in package.json must equal that same name. It is the ownership proof described above; without it the registry refuses the package.

The version fields track package.json — npm version keeps them in step via the version lifecycle script, so mcp-publisher publish also works from a clean local checkout. CI stamps them from the tag again before publishing, so the tag is what decides what ships.

License

MIT — see LICENSE.

Not affiliated with Render. spec/render-openapi.json is Render's published API description, vendored so builds are reproducible.