Two different things are called agents around Seed. Seed Agents is the hosted runtime that runs models for an account, with its own verbs, triggers and signed API. This page is about the other kind: an agent you run yourself, such as a Claude Code session, an MCP-capable assistant, a cron job or a bot, that reads and writes Hypermedia. The network does not know which kind of agent is talking. An agent is an account with a key, like a person.
What an external agent can use
Why there is no Seed MCP server
Seed does not run a hosted MCP server for its network, and this is on purpose. Everything an agent publishes on Hypermedia is a blob signed by the author's key: a document change, a comment, a capability. The signature is what makes the content trustworthy to every other reader. A hosted MCP server in the usual shape receives plain tool calls and acts on them remotely, so it would have to hold your private key and sign for you. Your keys should never leave your device, so that shape does not fit.
Signing happens where the key lives. The SDK and the CLI, which is built on the SDK, build and sign blobs locally. They then publish them to any site through the Seed API. An agent should use one of those, with a key of its own that the account owner delegates to (see below). Reads need no key at all, so a read-only integration can call the Seed API over plain HTTP.
If you still want an MCP interface for your own assistant, run it locally on the SDK, next to the key, so tools sign on your machine. Seed Agents works the other way. It is an MCP client, and its agents can call tools from any remote MCP server an account connects (MCP servers).
Reading
Any site answers over the Seed API without a key. A document in full: GET https://hyper.media/api/Resource?id=hm://<uid>/<path>. As markdown the way the CLI prints it: seed-cli document get hm://<uid>/<path>, or with embeds and mentions inlined, document get -r. Search: seed-cli search "<words>" -t hybrid -c 300 -l 40. Attribute queries: seed-cli query '*' -w 'has:childAttributesSchema'. See Query grammar.
To turn a web page URL into an id, ask the site. Any Seed page answers an OPTIONS request with X-Hypermedia-Id, X-Hypermedia-Version, X-Hypermedia-Title, X-Hypermedia-Type and X-Hypermedia-Authors headers. The CLI does this for you when you pass an https:// URL.
curl -s -X OPTIONS -I https://hyper.media/hm/<uid>/<path> | grep -i x-hypermediaIdentity: a key of the agent's own
Do not give an agent a person's account key. Give it a key and a capability:
seed-cli key generate -n bot --show-mnemonic on the agent's machine, or seed-cli key export a key from elsewhere and put the file's contents in SEED_CLI_KEYFILE.
The owner of the space grants it: seed-cli capability create --delegate <bot-uid> --role WRITER --path /drafts.
The agent creates documents under the space with -a <space-uid>. The CLI finds the capability and cites it. document update and document delete look the capability up without the flag.
Seed Agents use the same shape internally. Each hosted agent signs as its own identity and publishes into a shared space only through a capability that space issued. The AGENT role says "acts on behalf of". WRITER says "may write". Capabilities cannot be revoked today, so scope them to a path and rotate the bot's key when in doubt. Keys and Permissions have the details.
Attribution follows from the signature. Every change and comment the bot publishes names the bot's key as its signer, and the capability links it to the account. Give the bot a profile (seed-cli account profile set --name "Reports bot" -k bot) so readers see who it is.
Draft first
An agent that publishes on its own is hard to review. The seed-cli skill teaches this workflow, and it is the one to copy:
Research first: search, query, document get on the neighbours of where you intend to write. Confirm the parent path exists.
Write a draft: seed-cli draft create -f new-page.md --location hm://<uid>/<parent> (or --edit hm://<uid>/<path> for an edit). The draft lands in the Seed app's draft list on the same machine, where a person opens, edits and publishes it.
Publish only when asked, with an explicit path: seed-cli document create -f new-page.md -p <parent>/<slug> -a <space-uid>, or document update for an edit. Never publish to a path without confirming it.
Update in place: document update -f edited.md diffs by the block ids in the <!-- id:… --> comments, so round-trip the markdown you got from document get and keep those comments.
Comments are the low-risk write: seed-cli comment create hm://<uid>/<path> --body "…" on a document, or …#<blockId> on one block.
The seed-cli skill for Claude Code
A skill is a folder with a SKILL.md that Claude Code loads when a task matches it. The seed-cli skill teaches the CLI's install (npx -y @seed-hypermedia/cli@latest …), keys, drafts, the markdown and JSON input formats, and the draft-first workflow above. It is installed per user. The skills installer puts it in ~/.agents/skills/seed-cli and links ~/.claude/skills/seed-cli to it, where Claude Code finds it. It is not in the Seed repository. The repository's own docs/agent-setup.md asks that shared team workflows live in the repo's .agents/skills/ folder and not in a home directory. The CLI package also ships an older skill file as docs/CLI-REFERENCE.md (skill name seed-hypermedia) inside the npm tarball. Nothing installs it for you.
Both skills predate parts of the current CLI. When a skill and this documentation disagree, trust this documentation. In particular, --dev means https://dev.hyper.media plus the dev keyring and cannot be combined with --server. Keys come from the vault before the keyring. -a, --account exists. There is no seed-grpc skill.
Seed Agents, from the outside
For an agent that lives on the network, use Seed Agents. Its agents address the same things this page does through the five verbs read, write, call, delegate and plan, plus the session verbs status and continue_session. read takes hm://, ipfs://, https:// and the agent's own ~/memory/…, ~/tools/… and ~/triggers/… addresses. write takes the same except https://. call invokes search, query, attributes, web_search, execute or a tool projected from an MCP server. delegate spawns a child run, and plan keeps a checklist. Writes to hm:// go through the same SDK builders the CLI uses, with options.action choosing the operation: omitted for a new document, then update, move, redirect, fork, delete, comment, capability.grant, contact.create and the rest. See tools.
You can talk to a Seed Agents server from your own code through its signed API: a DAG-CBOR envelope signed by an account key or a delegated key, posted to /api/message. There is no standalone client library outside the Seed monorepo yet. The envelope and every action are documented in the signed API. A site advertises its agents to readers with the agentServerUrl and spaceAgents keys of its home document. See Metadata.
What to avoid
Publishing under a person's key. Use a bot key and a capability. The signature is the attribution.
Creating documents by hand from a genesis blob. Only the home document has a deterministic genesis. An ordinary document's first change is its genesis. The CLI and createDocumentBlobs get this right. A hand-rolled script that reuses the home genesis merges every new document into the home document.
Publishing linked blobs without CIDs. A blob published without its SHA-256 CID gets a BLAKE2b CID from the daemon, and anything that referenced it dangles. Keep the cid the SDK gives you.
Replacing a document's body wholesale. It works, but every block gets a new identity and every comment anchored to the old blocks loses its anchor. Round-trip the ids.
Mistaking a name for an identity. A key's name is local. Its z6Mk… id is the account.
Treating the local daemon API as private. A desktop daemon's HTTP port has no authentication. The desktop bridge on port 56004 refuses cross-site browser requests, but a local process can call it. Keep secrets out of what you publish. Everything public stays public forever.
Working with it
In the Seed app
Drafts an agent writes with draft create appear in the Seed app, where a person reviews and publishes them. The app's assistant panel is a Seed Agents client, so this page does not describe it.
CLI
Every command on this page is a CLI command. The reference is Seed CLI.
SDK
For an agent that runs continuously or exposes tools to a model, build on the SDK: createSeedClient for reads, createDocumentBlobs and the other builders for writes, keyfile.load for the bot key.
Web API
Reads need no key and work from any language. Writes are POST /api/PublishBlobs with blobs you signed. See Seed API.
Agents
In Seed Agents, this page's operations are the read, write and call verbs. The delegated-key model is the same, with the identity held by the agents server.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime