- Hyperclay
- Docs
- Data and APIs
- 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#
- In your workspace, open the account menu and choose Agent keys….
- Click New key….
- 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 itsapirules, 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.
- Name: what version history shows, for example
- 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:
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:
claude mcp add clay -- npx -y @panphora/clay-agent mcp
Claude Desktop (claude_desktop_config.json) or Cursor (.cursor/mcp.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#
| Tool | What it does | Access needed |
|---|---|---|
list_documents | List the documents the key can reach | Read |
read_document | Read a whole document, or an outline and then the parts it needs | Read |
outline_document | Show the element tree with selector paths and sizes | Read |
find_in_document | Find where some text appears | Read |
read_data | Read the page’s structured data through its api rules | Read |
list_versions, read_version | Read version history | Read |
list_sites | List the site folders the key can reach (each a folder holding its own site.json), with each one’s address and home page | Read |
list_files | List the folders, documents and files under one folder, with an etag for each | Read |
write_data | Change that structured data | Content |
edit_document | Replace exact text in the version it read | Edit |
save_document | Save a whole document | Edit |
restore_version | Restore an earlier version | Edit |
claim_subdomain | Give a document or a site folder its own <name>.hyperclay.com. A name that is already set is not changed | Edit |
add_domain | Add a custom domain to a document or a site folder and answer the two DNS records to set | Edit |
domain_status | Answer each custom domain’s status and DNS records | Edit |
publish_site | Upload a local folder as a site and answer what was created, replaced, unchanged and left alone | Edit |
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.
| Route | What it does | Access needed |
|---|---|---|
GET /documents/<id>/site-data | Read the site’s shared values, with an ETag | Read |
POST /documents/<id>/site-data | Merge top-level keys into them | Content |
PUT /documents/<id>/site-data | Replace them all | Content |
- Every write needs
If-Matchwith theETagfrom the read. Without it the write answers 428precondition-required. Ifsite.jsonchanged since the read, it answers 412conflictand changes nothing. - A narrow key never changes the whole site. A key limited to a folder cannot write a
site.jsonthat sits above that folder. It answers 404no-site-data, the same answer as a page that is in no site. - Shared values go through this route only.
write_dataon a page in a site refuses asitekey with 409site-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_datais refused on them. Edit them withedit_documentorsave_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.