Work from an agent
Find, save and change your items by asking an agent, and set up an agent that works on its own.
Once an agent is connected, as Connect your agent shows, you work with your items by asking in your own words. The agent acts with its own credential, so it reaches only what you approved, and every change it makes is recorded as its own.
Ask for what you want
An agent connected to your instance's MCP server can find, read, save and change items, and read and write the rows of a table. A few things to ask:
- Save a file from the web: "Save the PDF at this address to Marfa, tagged
taxes-2026." Your instance fetches the file itself and keeps it as a file item. - Find something: "What did I save about Lisbon?" or "Which of my photos are tagged
garden?" - Save what you're working on: "Save this summary as a note, and link it to the bookmark it came from."
- Change an item: "Mark the boiler service task done," or "Tag these three bookmarks
reading." - Tidy up: "Move the notes tagged
scratchto the bin."
The agent starts by reading the overview of your instance: the types, tags and views it can reach. If it needs access you didn't approve, a client that supports it asks you to approve more on your instance's approval page.
What the agent does before it changes anything
- It reads before it writes. A change names the version of the item the agent read. If the item changed since, from your editor or another agent, nothing is written and the agent reads it again.
- It asks before it deletes. Moving items to the bin, or moving items to another type, first shows what would change. The agent shows you, and acts only once you agree.
- It never purges. Nothing an agent does deletes an item for good: what it moves to the bin waits there for you to restore.
An agent that runs on its own
An agent that runs on a schedule, such as a nightly digest, has nobody to approve it in a browser. Give it a key of its own, holding only the types it needs. This key reads bookmarks, reads and edits notes, and stops working after 30 days:
marfa keys create --label "Reading digest" --source reading-digest \
--type-permission core.bookmark=read \
--type-permission core.note=write \
--expires-in 30dmarfa_k1_9QeT…
key 01a1f130-37fc-7184-b4a2-3fba803cf8be (Reading digest); the plaintext is shown once, keep it now
core.bookmark Read only
core.note Read and editKeep the key in your password manager now: it's shown once. Every item the agent creates carries its source, reading-digest, so you can tell its work from yours. Manage keys covers what else a key can hold.
Put the key in MARFA_API_KEY in the agent's environment, and have its client send it as a header. The client reads the variable when it connects, so the key stays out of every file:
claude mcp add --transport http --scope user marfa https://marfa.example.com/mcp \
--header 'Authorization: Bearer ${MARFA_API_KEY}'Keep the single quotes, so your shell doesn't fill in the key.
An agent that runs commands
A coding agent that runs shell commands can use the CLI instead, which has a command for every operation in the API except approving an app, which happens in a person's browser. Give it a key of its own, as above, and a profile whose key_command reads the key from your password manager:
[digest]
url = "https://marfa.example.com"
key_command = ["op", "read", "op://Private/Marfa/reading-digest"]Set MARFA_PROFILE=digest and MARFA_NO_KEYCHAIN=1 where the agent runs its commands. With the keychain off, a command that names no server is refused, so the agent reaches no instance but the one its profile names. marfa overview then shows the agent what its key reaches, and what's there:
marfa overviewinstance Marfa (0.0.80)
credential key Reading digest
can read and write core.note
can read core.bookmark
types, 2 items in all
core.note (2) Text you wrote, such as a thought, a meeting note or a list.
core.bookmark (0) Something you saved from elsewhere, such as a link, a highlighted excerpt or a clipped paragraph.
tags
lisbon (1)Tell the agent how to work in its instructions file:
## Marfa
Marfa holds the files and records I keep. Use the `marfa` CLI with `--json`.
- See what the key reaches: `marfa overview --json`
- Find items: `marfa search "<words>" --json`
- Read one: `marfa items get <id> --json`
- To change one, read it first and pass its `version` to `marfa items update`.Work from the command line shows the everyday commands.
See what an agent did
Every change an agent makes is in the audit log under its own name, and each item it wrote names the agent as the writer of that version. You can cut an agent off at any time: revoke its key, or end its sign-in, as See and cut access shows. Its next request is refused, and what it wrote stays.