# Work from an agent (/use/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](/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 [#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 `scratch` to 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 [#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-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:

```bash
marfa keys create --label "Reading digest" --source reading-digest \
  --type-permission core.bookmark=read \
  --type-permission core.note=write \
  --expires-in 30d
```

Output:

```text
marfa_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 edit
```

**Keep 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](/run/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 Code**

```bash
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.

**Codex**

```bash
codex mcp add marfa --url https://marfa.example.com/mcp --bearer-token-env-var MARFA_API_KEY
```

## An agent that runs commands [#an-agent-that-runs-commands]

A coding agent that runs shell commands can use the [CLI](/reference/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](/reference/cli#name-a-server-with-a-profile) whose `key_command` reads the key from your password manager:

```toml title="profiles.toml"
[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:

```bash
marfa overview
```

Output:

```text
instance 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:

```markdown title="AGENTS.md"
## 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](/use/command-line) shows the everyday commands.

## See what an agent did [#see-what-an-agent-did]

Every change an agent makes is in the [audit log](/use/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](/use/see-and-cut-access) shows. Its next request is refused, and what it wrote stays.
