# Set up Render for your coding agent

This is a procedure. Execute the steps in order. It is idempotent: running it again is safe, it never overwrites MCP servers or skills that you did not install, and it merges into existing configuration instead of replacing it. Authentication and UI-only setup actions require a human; complete everything else yourself.

## Step 1 - Identify yourself

Determine which agent product you are. Map the signal to the guide, then read that guide before continuing.

| Agent | Signal | Guide |
| --- | --- | --- |
| Claude Code | `~/.claude.json` or `~/.claude/` | https://render.com/agents/claude.md |
| Cursor | `~/.cursor/` | https://render.com/agents/cursor.md |
| Codex CLI | `codex` terminal session | https://render.com/agents/codex.md |
| OpenCode | `~/.config/opencode/` | https://render.com/agents/opencode.md |
| Pi | `~/.pi/agent/` | https://render.com/agents/pi.md |
| Claude Desktop | macOS app, no CLI | https://render.com/agents/claude-desktop.md |
| Codex Desktop | Codex in the ChatGPT desktop app | https://render.com/agents/codex-desktop.md |

Prefer your own knowledge of which product you are over filesystem signals. A configuration directory can exist for an agent that is not currently running, so the presence of `~/.cursor/` does not mean you are Cursor.

If you cannot determine which product you are, ask the user. Do not guess.

If no row matches, use the generic API key path described in Step 2 and configure the MCP server with the standard remote server settings in Step 3.

The machine-only **Setup contract** in the guide you select is the source of truth for the preferred setup method, MCP ownership, fallback commands or configuration, authentication, restart requirements, and skills verification.

## Step 2 - Authenticate (requires a human)

Only a human can authorize access. State clearly which mode you need. For OAuth, ask the human to approve the browser flow when it opens; do not ask for a token. For an API key, ask the human to set `RENDER_API_KEY` in the environment read by the agent process; do not ask them to paste the key into chat.

Do not stop working while you wait. Steps 3 and 4 never contain the credential value, only a
reference to its environment variable name, so complete them regardless. Only the verification in
Step 5 needs a working credential.

There are two authentication modes. Pick one.

### OAuth (preferred)

The Render MCP server supports OAuth. It is preferred because no secret is written to disk. Whether *your* tool can use it depends on the tool: the guide from Step 1 is the source of truth, and it documents an OAuth flow only when one exists for that tool. Claude Code, Claude Desktop, Codex CLI, Codex Desktop, Cursor, and Pi have documented flows.

If your guide documents an OAuth flow, ask the human to complete it. The flow opens a browser and requires the human to approve access.

OAuth authorizations expire. When one does, the tool reports a 401 or prompts to reconnect, and a human has to approve the browser flow again. An API key does not expire, which is why it is the required mode for non-interactive and CI environments. Tell the human about this trade-off when they pick a mode, so an expired session later reads as expected behavior rather than a broken setup.

### API key

An API key is required for any non-interactive or CI environment, and for any tool whose guide from Step 1 documents no OAuth flow. It is also the right choice when the human wants a credential that does not expire.

Ask the human to generate a key at https://dashboard.render.com/u/settings#api-keys

Rules for handling the key:

- Reference the key through the `RENDER_API_KEY` environment variable.
- Never write a key into a file that could be committed. That includes repository configuration files, `.env` files that are not ignored, and shell scripts in the repository.
- Never invent, guess, or reuse a key from another source.

Continue to Step 3 now. Come back to verification in Step 5 once the human confirms the credential is
in place.

## Step 3 - Apply the preferred setup

Read the Setup contract from the guide selected in Step 1, then use its **Preferred setup method** and **Preferred setup command**.

- If a plugin, package, or connector provides MCP, install or enable it first. Do not also write a manual `render` MCP entry.
- If the setup action is in a desktop UI, ask the human to perform it and continue with any non-UI work while you wait.
- Do not reinstall an integration that is already present. Update it only when the existing installation cannot provide the documented MCP or skills behavior.
- After the integration loads, complete the selected OAuth flow or make sure `RENDER_API_KEY` is available to the agent process.

## Step 4 - Fill only the missing pieces

### MCP fallback

Check whether the `render` MCP server is available before editing configuration. If it is missing:

1. Use the Setup contract's **Manual OAuth command** when OAuth was selected.
2. Otherwise use its **API key fallback command** or **API key fallback config**. Reference the key through the named environment variable; never put the key value in a repository file.
3. If the contract has no applicable fallback, read its **Fallback reference**.

When editing a config file, read it first and merge the `render` entry without replacing other MCP servers. The server name is `render` and the URL is `https://mcp.render.com/mcp`.

### Skills fallback

Read **Skills supported** from the Setup contract.

- If it is **No**, skip skills installation and verification.
- If the preferred plugin or package installed skills, do not install a duplicate copy.
- Otherwise run the contract's **Skills fallback command**. If none is provided, use `npx skills add render-oss/skills`.
- Use `render skills install` only when Render CLI 2.10 or later is already installed. Do not install the CLI solely for this command.

## Step 5 - Verify

Call the MCP tool `list_workspaces`.

A successful response from `list_workspaces` is the definition of done. If the call fails, go to the troubleshooting section below.

If more than one workspace is returned, ask the human which workspace to use, then record that choice where your guide says workspace selection belongs.

If **Skills supported** is **Yes**, verify them too. List the concrete **Skills directory** from the Setup contract when one exists. For a plugin-managed directory, verify that the plugin is enabled and that Render skills appear in a new session instead of guessing a filesystem path.

## Step 6 - Report to the user

Report:

- What changed: MCP server added, skills installed, authentication mode used.
- Exactly which files you edited, by absolute path.
- What remains for the human: any restart, any workspace selection, and anything you skipped.

## If something fails

- The Render MCP tools do not appear: reload the plugin or restart the agent if the Setup contract says a restart is required. Do not add a duplicate manual MCP entry until the preferred integration has reloaded and still does not provide one.
- A 401 on a connection that worked before: the OAuth authorization has expired. This is the most common cause, and it is not a misconfiguration — do not rewrite the MCP configuration or switch the user to an API key to work around it. Ask the human to reconnect the Render MCP server in their tool and approve the browser flow again, then call `list_workspaces` to confirm. Only a human can complete this step.
- A 401 on a connection that has never worked: re-check the authentication mode from Step 2. Confirm OAuth is supported for your agent, or confirm `RENDER_API_KEY` is set in the environment the agent reads and that the key has not been revoked.
- Skills do not load: for standalone skills, confirm the concrete directory from the Setup contract and rerun the skills fallback command. For plugin-managed skills, update or reload the plugin and start a new session.

## After setup

- Task routing: https://render.com/agents/tasks.md
- Render MCP server reference: https://render.com/docs/mcp-server.md
- Render skills and LLM support reference: https://render.com/docs/llm-support.md

## Setup guides

- Claude Desktop + Render: https://render.com/agents/claude-desktop.md
- Claude Code + Render: https://render.com/agents/claude.md
- Codex Desktop + Render: https://render.com/agents/codex-desktop.md
- Codex CLI + Render: https://render.com/agents/codex.md
- Cursor + Render: https://render.com/agents/cursor.md
- OpenCode + Render: https://render.com/agents/opencode.md
- Pi + Render: https://render.com/agents/pi.md