Docs / MCP

Manage your name from an agent

runs-on.dev runs a Model Context Protocol server at https://runs-on.dev/.well-known/mcp. Connect Claude Code, Codex, Cursor, or any MCP client, sign in once in the browser, and your agent can point your DNS, publish a site, and roll it back, all on the name you own.

1. Add the server

Claude Code:

claude mcp add --transport http runs-on https://runs-on.dev/.well-known/mcp

Codex:

codex mcp add runs-on --url https://runs-on.dev/.well-known/mcp

Cursor, in ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "runs-on": { "url": "https://runs-on.dev/.well-known/mcp" }
  }
}

VS Code, in .vscode/mcp.json:

{
  "servers": {
    "runs-on": { "type": "http", "url": "https://runs-on.dev/.well-known/mcp" }
  }
}

Any other client: a Streamable HTTP server at that URL. It supports standard MCP OAuth, with dynamic client registration and PKCE. You don't need to sign in before connecting: the two public tools work right away.

2. Sign in

In Claude Code, run /mcp, pick runs-on, and choose Authenticate. In Codex, run codex mcp login runs-on. Cursor and VS Code show a sign-in prompt next to the server. If you skip this, the first owner tool you use asks you to sign in.

A browser opens on runs-on.dev. Sign in with GitHub as usual, then approve. You choose what the agent gets: deploys only, or deploys plus editing your DNS. The agent stores the resulting token itself, and it lasts 30 days.

Check that the address shown on the approval page matches your agent (usually localhost). Every login appears as a key under Deploy & agent token on /manage, and deleting it there cuts the agent off immediately.

3. Ask for what you want

Plain requests work. For example:

Point my runs-on.dev name at my GitHub Pages site, zord.github.io.

Add a _discord TXT record with the value Discord gave me: dh=abc123.

Build this project and deploy dist/ to my runs-on.dev name.

The last deploy broke the homepage. Roll back to the one before it.

The agent calls whoami and get_record to see where things stand, then sends only the fields it is changing. Every edit goes through the same validation as the /manage editor and pull-request CI. It lands as a public commit in the registry, and DNS follows within minutes.

Tools

tool	needs	does
`check_name`	none	Is a name available to claim?
`get_record`	none	Any claimed name's public record.
`whoami`	signed in	Your login, the token scope, and the names you own.
`update_records`	signed in + DNS	Replace the apex records, subdomains, or profile card.
`deploy_site`	signed in	Publish static files to https://<name>.runs-on.dev/.
`list_deployments`	signed in	Deployment history and which one is live.
`rollback_site`	signed in	Re-point the live site at an earlier deployment.

update_records takes the same shapes as the record reference. The apex is { "CNAME": "host" } alone, { "URL": "https://…" } alone, or any mix of A, TXT, and MX. An empty {} puts the name back on its profile card. deploy_site takes a list of { path, content, encoding } files with index.html at the root, which suits small sites. For anything over a few MB, use the zip upload at POST /api/sites/deploy.

CI and scripts: use a token instead

Where no browser is available, generate a token on /manage (tick also edit DNS for update_records) and send it as a header:

claude mcp add --transport http runs-on \
  https://runs-on.dev/.well-known/mcp \
  --header "Authorization: Bearer rod1.YOUR_TOKEN"

# Codex reads it from the environment
export RUNS_ON_TOKEN=rod1.YOUR_TOKEN
codex mcp add runs-on --url https://runs-on.dev/.well-known/mcp \
  --bearer-token-env-var RUNS_ON_TOKEN

Troubleshooting

needs you to sign in / auth_required: The agent has no token for runs-on.dev yet. Sign in (step 2). Claude Code shows the server as connected before this, because the public tools work without a login.
invalid_token or revoked_token: The token expired after 30 days, or it was deleted on /manage. Sign in again.
insufficient_scope: The agent tried to edit DNS with deploy-only access. Sign in again and pick “deploys plus DNS” on the approval page, or generate a token with also edit DNS ticked.
no_claimed_name or not_your_name: The GitHub account you signed in with doesn't own a name, or doesn't own the one the agent named. Claim a name first, or sign in with the account that owns it.
invalid_record: The edit broke a record rule. For example, a CNAME can't sit beside other records. The details list says which rule, and the record reference has them all.
rate_limited: Per account, every 10 minutes: 12 record edits, 6 deploys or rollbacks, 30 reads. Wait retryInMs and try once more.
stale: Something else changed the record or the site while the agent was writing. Read it again, then retry.
The approval page says “Cannot authorize this app”: The app sent a malformed request. Remove the server from your agent, add it again, and sign in from scratch.

What it cannot do

It cannot claim, swap, or release a name. Those stay in the browser behind your GitHub sign-in, because a token in an agent is the wrong place for an action you cannot undo. It also cannot touch a name you do not own: every tool checks ownership on the server, and writes share the same per-account rate limits as the website.