Agent tokens
Give an AI agent its own key that opens only the folders you choose. Say your research bot should read Research, write in Drafts, and never see the rest of Personal: that is one agent token. It is on every plan.
This is for agents and apps that take a token, such as Claude Code, Cursor or your own scripts. ChatGPT, Claude.ai and Claude Desktop connect by signing in instead. They reach everything you can, unless you limit them on the sign-in screen to some folders, to reading only, or both. The same rules as below apply, and you can change it later under Settings > Connections. There you can also name each one, so with two Claude sessions, note history says which one made each edit.
Follow the ChatGPT and Claude client-folder walkthrough to check an allowed read, an out-of-scope read and a read-only write.
Set it up
- Open Settings › Connections, name the token after the agent, such as Research bot, and press Create token.
- Copy the token now. It is shown once: Hjarni keeps only a fingerprint of it.
- Under Folders, pick a level for each folder the agent should reach.
- Optionally, tell it what it's for in Instructions for this agent (more below). Then press Save access.
A new token starts with no folders, so an agent you forget to set up finds none of your notes rather than all of them.
The agent cannot see the folder or anything in it.
It can search and read, but change nothing.
It can also create, edit, move and delete notes and folders there.
A level covers every folder inside, until one sets its own. So Write on Drafts with Drafts › Private set to No access keeps that one folder out. The Personal row covers your whole space, Inbox included, and each team has a row of its own.
Handing one folder to several agents? Open the folder, choose Edit folder, then Permissions: every agent token is listed there with its level.
Tell it what it's for
On the token's page, Instructions for this agent is where you tell it its job. For example: "Summarise each new note in Research in three sentences, and write in English even when the source is Dutch." Only this agent gets them, and it cannot change them. A change reaches it the next time it connects.
It also follows your AI instructions (the ones on the AI Instructions page), and the instructions of the folders it works in, which win inside their folder. If your AI instructions are written for your chat assistant and don't fit this agent, untick Also follow my AI instructions. Copy over any naming or tagging rules it should keep.
Instructions steer the agent. Only its folders decide what it can reach.
What it can see
Only the folders you gave it. Search, lists, tags and counts leave out everything else, nothing names a folder it was not given, and a note outside its folders reads as not found.
A few things belong to the whole account, so every agent token can read them, even one with no folders yet:
- your account id, first name and email address, plus your plan over the REST API
- the instructions you wrote for it
- your AI instructions, unless you turned them off for it
Never more than you have
- Where you can only read, so can the agent: in a team folder where you are a viewer, and in any folder someone else shared with you.
- If you are removed from a team, the agent loses its access there for good.
It also can't change anything about your account: who you share with, your teams, your tag list, your email addresses or your AI instructions.
Detailed permissions
Read covers notes, folders, files, links and history. Write adds archiving, restoring, attaching files and managing links.
Moving a note needs Write on the folder it is in and on the one it goes to. Moving a folder needs Write on that folder, on every folder inside it, and on the one it goes to. Linking two notes needs Write on both, because a link changes the backlinks of the note it points to.
It can tag notes it can write. A new tag name joins the tags of the note's owner, and other agent tokens see it only on notes they can read. It cannot rename, merge or delete tags, since they are one list for the whole account.
Instructions of the folders above its own still apply to it. Over MCP they arrive labelled as coming from a folder above, without that folder's name, and a folder path starts at the highest folder it can read.
Where it has Write in your own folders, it can change those folders' instructions. It can never change its own instructions or your AI instructions.
It sees the teams it reaches and the levels it holds through me, but no account-wide totals, such as how many notes you have.
Connect it
In Claude Code it is one command. Add --scope user to use it in every project.
claude mcp add --transport http hjarni https://hjarni.com/mcp \
--header "Authorization: Bearer YOUR_AGENT_TOKEN"
For Cursor and other MCP clients see the MCP reference, and for scripts the REST API reference. The same token works for both.
Check or stop it
Its changes to a note's text, title or folder are signed with its name in note history, such as Written by Research bot, and you can restore an earlier version like any other. Tag changes are not in note history.
On the token's page in Settings › Connections you can change its folders and instructions at any time; access changes apply on its next request. Make a new token swaps in a new secret if the old one leaked, keeping its name, access and history. Revoke cuts it off at once.
For developers: what a refusal looks like
Over the REST API, a note or folder it cannot see returns 404, and a write where it can only read, or into a folder it was not given, returns 403 with "error": "Forbidden: outside token scope" and "code": "out_of_scope".
Over MCP, a refusal for access or a limit is never a protocol error. It comes back as an ordinary tool result, in one of two shapes. Some answer with ok: false and a status, such as blocked or not_found. Others, such as a write where it can only read, answer with error: true and text that starts with Error:. Check for both before treating a call as done: a model left to itself can report a refused write as saved. A malformed call still gets a JSON-RPC error, and a revoked token gets HTTP 401.
Over MCP the agent's instructions arrive with the server instructions on connect, and again through me and instructions-get at level brain. Over REST, /api/v1/me returns them in its token block.
Common questions
FAQ
What is an agent token?
A token you make for one agent, script or integration, such as Claude Code or a research bot, that reaches only the folders you give it. Per folder or space you choose No access, Read or Write, and that passes down to the folders inside until one sets its own.
Is it a Pro feature?
No. Agent tokens are on every plan, Free included, like the MCP server and the REST API.
What can a new agent token reach?
No folders. An agent you forget to configure finds none of your notes rather than all of them. It can still read a few account-wide details, such as your email address and, over MCP, your AI instructions; the full list is under What it can see. Give it folders on its page in Settings › Connections, or from a folder's Permissions tab.
Can an agent get more access than I have?
No. Its level is capped by yours: in a team folder where you are a viewer it reads at most, and in a folder someone shared with you it reads at most too. If you are removed from a team, its levels there are removed.
Does it work with ChatGPT or Claude.ai?
Not as a token: ChatGPT, Claude.ai and Claude Desktop connect by signing in. They reach everything you can, unless you limit them on the sign-in screen to some folders, to reading only, or both, with the same rules as an agent token. An agent token is for clients that take a Bearer token: Claude Code, Cursor, custom MCP agents and anything calling the REST API.
How do I tell its edits from mine?
Its changes to a note's text, title or folder are signed with the token's name in note history, and you can restore an earlier version of the text like any other.
What happened to my old tokens?
A token with full access keeps it until you limit it on its page. A token that was limited to one folder became an agent token with Write on that folder. It reaches the same folder as before, and now works over MCP as well as the REST API.
Related docs
Questions about agent access?
Email evert@hjarni.com
Give your AI a memory. Free.
Connect Claude or ChatGPT to notes they can actually read and write.
Give your AI a memory. Free.