Hyperclay
  1. Hyperclay
  2. Docs
  3. Data and APIs
  4. Edit with AI agents

Edit with AI agents

Make an agent key and let Claude Code, Claude Desktop, Cursor or any MCP client read and edit Hyperclay documents, with every change in version history.

Your own AI agent can read and edit your Hyperclay documents. Make an agent key in your workspace, sign in with it once on your computer, and connect Claude Code, Claude Desktop, Cursor or any other MCP client through @panphora/clay-agent. Agent keys are available on every plan, free included.

The agent acts as you, with no more access than you have, and you can narrow it further: one team or one folder, and reading only, content only, or full editing. Every change it saves is kept in the document’s version history as Recorded by <your name> through <key name>, so any change can be restored.

Make an agent key#

  1. In your workspace, open the account menu and choose Agent keys….
  2. Click New key….
  3. Fill in the form:
    • Name: what version history shows, for example Claude on my laptop.
    • Access: Edit documents (read, change content, save whole documents, create and replace files and folders such as pages, images, CSS and site.json, publish a local folder as a site, restore versions, claim subdomains for documents and site folders, and add custom domains and read their status and DNS records), Change content only (read, and change the data a page exposes through its api rules, with no changes to the page’s code), or Read only.
    • Documents: everything you can open, your personal documents, one team’s documents, or one folder.
    • Expires after: 1 year, 90 days or 30 days.
  4. Click Make key.

The key starts with hcak_ and is shown only once. Copy it before you click Done.

Connect your agent#

Sign in once on your computer, and paste the key when it asks:

Shell
npx -y @panphora/clay-agent login

The key is saved in ~/.config/clay-agent/credentials.json, readable only by you, so it never goes into an agent’s config file. Setting CLAY_AGENT_KEY in the environment works instead.

Then add the MCP server.

Claude Code:

Shell
claude mcp add clay -- npx -y @panphora/clay-agent mcp

Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.json):

JSON
{
  "mcpServers": {
    "clay": { "command": "npx", "args": ["-y", "@panphora/clay-agent", "mcp"] }
  }
}

If Node is installed through nvm, use the absolute path to npx (which npx) as the command. Add --read-only after mcp to offer the agent only the reading tools.

Now ask your agent for something, such as “add a due date column to my tasks document”.

What the agent can do#

ToolWhat it doesAccess needed
list_documentsList the documents the key can reachRead
read_documentRead a whole document, or an outline and then the parts it needsRead
outline_documentShow the element tree with selector paths and sizesRead
find_in_documentFind where some text appearsRead
read_dataRead the page’s structured data through its api rulesRead
list_versions, read_versionRead version historyRead
list_sitesList the site folders the key can reach (each a folder holding its own site.json), with each one’s address and home pageRead
list_filesList the folders, documents and files under one folder, with an etag for eachRead
write_dataChange that structured dataContent
edit_documentReplace exact text in the version it readEdit
save_documentSave a whole documentEdit
restore_versionRestore an earlier versionEdit
claim_subdomainGive a document or a site folder its own <name>.hyperclay.com. A name that is already set is not changedEdit
add_domainAdd a custom domain to a document or a site folder and answer the two DNS records to setEdit
domain_statusAnswer each custom domain’s status and DNS recordsEdit
publish_siteUpload a local folder as a site and answer what was created, replaced, unchanged and left aloneEdit

Agents cannot delete, rename, move or share anything, cannot make a private page public, cannot remove a custom domain, and cannot change a subdomain once it is set. Every file they replace needs the etag they read: a replaced page is kept in version history, and a replaced file’s old bytes are kept as a backup.

The same commands work from a terminal, for scripts: clay-agent list, clay-agent read, clay-agent edit, clay-agent publish and more. Run npx -y @panphora/clay-agent --help, or see the package README.

Safe by default#

  • Nothing is overwritten silently. Every write is based on the version the agent read. If you or someone else changed the document or file in the meantime, the write is refused and the agent is told to read it again.
  • Every document change can be undone. Each agent save is a new version in version history, named after the key that made it. If the document had unsaved edits open in a browser, they are kept as a version first. Subdomain claims and custom domains change where a document or site answers, not its content, so they are not in version history and cannot be restored from there.
  • Keys can claim subdomains, not change them. A key with Edit documents access can give a document or a site folder it can reach the public address <name>.hyperclay.com, and claiming the name it already has changes nothing. A key cannot change a subdomain once it is set. That takes the dashboard. Private pages stay private, and a private document’s address does not serve until the document is public. The same rules as the dashboard apply: subdomains need a paid plan, the plan’s subdomain limit applies, and reserved words and names already in use are refused.
  • Writes are limited. A key can make 60 page saves a minute and 300 file writes a minute, so an agent stuck in a loop cannot fill your history. You can have up to 10 active keys at a time.
  • Keys stay out of documents and files. A save, data write or file write that contains an agent key is refused.

Site data#

A page in a multi-page site takes shared values, such as the site’s name and its navigation links, from the site’s site.json. An agent changes a shared value in site.json, not on a page, and the change reaches every page in the site. Call these routes on https://hyperclay.com/_/agent/v1 with the key in an Authorization: Bearer hcak_... header. <id> is the id of any page in the site.

RouteWhat it doesAccess needed
GET /documents/<id>/site-dataRead the site’s shared values, with an ETagRead
POST /documents/<id>/site-dataMerge top-level keys into themContent
PUT /documents/<id>/site-dataReplace them allContent
  • Every write needs If-Match with the ETag from the read. Without it the write answers 428 precondition-required. If site.json changed since the read, it answers 412 conflict and changes nothing.
  • A narrow key never changes the whole site. A key limited to a folder cannot write a site.json that sits above that folder. It answers 404 no-site-data, the same answer as a page that is in no site.
  • Shared values go through this route only. write_data on a page in a site refuses a site key with 409 site-data, which points to this route.

A write answers the same way as the site data API, including how many pages were updated and which failed.

Sites and addresses#

A site folder is a folder that holds its own site.json. An Edit key can give it a subdomain with claim_subdomain({ site: "demos/maya", subdomain: "maya" }). Pages in the folder then load at https://maya.hyperclay.com/, and private pages stay private. To use your own domain, call add_domain, set the two records it answers (a traffic record, and a CNAME at _acme-challenge that proves you own the name), then call domain_status until the domain shows active. Agents can add domains but never remove them; remove one in the dashboard.

Publishing a folder#

An Edit key can create and replace files and folders (pages, images, CSS and site.json), and publish_site({ folder: "./maya", to: "demos/maya", subdomain: "maya" }) uploads a local folder as a site. It sends only files that changed, creates site.json if neither side has one, never deletes files that exist only on hyperclay.com (it lists them as remoteOnly), and claims the subdomain last. Run it with dryRun: true first to see the plan, or from a terminal with npx -y @panphora/clay-agent publish ./maya demos/maya --subdomain maya --dry-run. Use a key scoped to the one folder you are publishing.

Limits#

  • Documents can be at most 5 MB. Large documents are read in pieces: an outline first, then the parts the agent needs.
  • Upload size and storage follow the account’s plan. Free accounts can upload images only.
  • File writes are limited to 300 a minute per key, and page saves to 60 a minute. Replacing a page counts toward both.
  • Adding a custom domain or reading its status needs the Add domain permission on the account, so a team editor’s key cannot do either.
  • One data write can change at most 1,000 rows.
  • Documents made with the page editor keep their content outside the HTML, so write_data is refused on them. Edit them with edit_document or save_document.

Revoke a key#

Open Agent keys…, find the key under Active, click Revoke and confirm. Agents using it stop working at once, and changes they already made stay in version history. Expired and revoked keys are listed under History, and Recent activity in the Agent keys dialog shows recent changes per key.

Agent keys and sync keys#

A sync key (hcsk_) is for Hyperclay Local and scripts that copy whole files back and forth. It has your full access to your own and your teams’ documents. An agent key is made for AI agents: it is named, can be limited to a team or folder and to an access level, and its changes are labeled in version history. Use an agent key for an AI agent.