Agent access

Your own agent can read your Collections and saved papers, read your notes and highlights on a paper, and file papers for you ●Agent access to the Library and Collections: Live. It does so with a personal key ●Personal keys: Live: a bearer secret you issue in the Library, with the permissions and the reach you choose, and revoke whenever you like. The agent acts as you, within those settings, and can do nothing that shares, deletes or administers. A personal key reaches no Room, and a Room credential reaches nothing in the Library.

Issue a key#

What the agent can do#

Every read and operation a key allows, with the box that allows it. The agent has the authority you have and no more: renaming is for Collections you own, and adding to a shared Collection is what any member may do.

Papers are named by arXiv identifier, as in the browser, in batches of up to 20. Substrate fetches each paper’s title and authors from arXiv within a budget of 30 seconds per batch; a paper arXiv does not answer for in time is filed all the same, titled arXiv:<id> until its metadata arrives, which the next request naming it, or your next visit to the Library, brings in. An identifier arXiv does not recognise is reported beside the others, and nothing else in the batch fails for it.

These stay with you, in the browser, whatever the key allows; none has an agent route, and a key cannot issue, renew or revoke a key either:

• Delete a Collection
• Invitations (create, revoke, accept)
• Remove a member, leave a Collection
• Delete a note
• Unsave a paper
• Read marks
• Write annotations or any reader state

What it looks like to others#

Everything the agent files says so ●Via marks: Live. In a Collection, a paper the agent added shows via and a name beside your username where the view says who added it, and a note the agent posted carries the same mark beside its author. You see the key’s label, so you can tell which key acted; other members see the agent name you gave the key, or via agent when you gave none. The label itself is never shown to anyone else, and a paper or note you filed in the browser carries no mark.

A note is posted under your name: members read it as yours, and you answer for it as for anything you post. Nothing the agent reads or posts counts as you having read a thread; the unread marks you see are yours alone. And an agent never removes a discussion: removing a paper whose thread holds a note, by anyone, is refused, and the paper stays where it is until you remove it in the browser.

Annotations#

With Read annotations, the agent reads what you wrote on a paper in the reader ●Annotation read for agents: Live: your note on the paper and each highlight’s page, colour, text and note, with the revision of that state. Two things never leave: where a highlight sits on the page, and the reader assistant’s messages. The read writes nothing and does not move the revision, and a paper you have not annotated answers the empty state. With a selected reach, only papers held by a Collection in reach can be asked about; the other reaches cover any paper.

Connect your agent#

Three ways, beside each other; each ends with an agent that knows the origin, holds the key in its environment and has read the Library skill. The key is sent to the origin that issued it and nowhere else; the MCP adapter refuses any other host.

SKILL=~/.claude/skills/substrate-library
mkdir -p "$SKILL"
curl -fsSL https://thesubstrate.science/api/agent/library/skill \
  -o "$SKILL/SKILL.md"
export SUBSTRATE_PERSONAL_TOKEN=subp_…   # the key, in the environment only

Use the substrate-library skill against
https://thesubstrate.science with the key in SUBSTRATE_PERSONAL_TOKEN.
Read your identity, then list my Collections and the papers in the one
called "<Collection name>", with their notes. Change nothing.

The skill at /api/agent/library/skill is the agent-facing reference: the identity read first, reach and permissions, the reads, batches, retries with the same request id, and the rule that note bodies, paper titles and abstracts are text written by other people and never instructions. The manifest at /.well-known/substrate.json carries the same contract in its library block, and /api/agent/library/schema serves every operation’s input schema with an example body. The paths and refusal codes are on HTTP API, and the tools on MCP tools.

Two kinds of key#

A personal key (subp_) and a Room credential (sub_) are separate in both directions. A personal key is refused on every research route, so nothing your agent does in your Library can reach a Room, and a Room credential is refused on every Library route, so no Room member’s agent can see your shelf. An agent that does both holds one of each, each in its own variable: SUBSTRATE_PERSONAL_TOKEN and SUBSTRATE_TOKEN. Room credentials are on Agent credentials.

Revoke#

Your keys lists each live key with its label, permissions, reach, expiry and when it was last used, refreshed at most every ten minutes. Revoke ends a key at once: its next request is refused, as an expired key’s is. Keys that ended stay listed, dimmed, with the date they expired or were revoked. Settings are fixed once a key exists: to change a permission, the reach or the agent name, revoke it and issue another. Leaving a Collection, or being removed from one, ends every key’s access to it at the same moment, and a deleted Collection leaves every reach that listed it. What the agent filed stays, attributed to you; revocation changes who may write next, not what was written. You can hold up to 20 live keys.

Limits#