> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Interface

> How AI agents read and write markdown in KiwiFS.

KiwiFS gives agents four ways to access markdown, from the most native (filesystem) to the most structured (MCP).

## Filesystem access

When your agent has a real filesystem mount (NFS, FUSE, or local):

```bash theme={null}
cat /kiwi/concepts/authentication.md
grep -r "timeout" /kiwi/
ls /kiwi/reports/
echo "# New finding" > /kiwi/reports/finding-042.md
```

Agents already know these commands from training data. No SDK, no driver, no custom protocol.

## REST API

When a filesystem mount isn't available:

```bash theme={null}
# Read a file
curl localhost:3333/api/kiwi/file?path=concepts/auth.md

# Write a file (with attribution)
curl -X PUT 'localhost:3333/api/kiwi/file?path=reports/finding.md' \
  -H "X-Actor: agent:exec_abc" \
  -H "X-Provenance: run:run-249" \
  -d "# Finding..."

# Search
curl 'localhost:3333/api/kiwi/search?q=timeout'
```

## MCP (Model Context Protocol)

The most structured interface, designed for Claude, Cursor, and other AI tools:

```bash theme={null}
kiwifs mcp --root ~/knowledge          # in-process, no server needed
kiwifs mcp --remote http://host:3333   # proxy to a running server
```

**60+ MCP tools** cover files, search, DQL, imports, analytics, drafts, saved views (Bases), canvas, workflows, claims, graph analytics, linting, clipping, and more. See the grouped reference in [MCP](/concepts/mcp).

See [MCP](/concepts/mcp) for transport options, HTTP security notes, and resource URIs.

## Access protocols

Every protocol flows through the same storage layer. Every write — regardless of how it enters — gets a git commit, a search index update, and an SSE broadcast.

<Mermaid>
  flowchart TD
  subgraph Protocols
  REST\["REST API :3333"]
  NFS\["NFS :2049"]
  S3\["S3 :3334"]
  WebDAV\["WebDAV :3335"]
  FUSE\["FUSE mount"]
  MCP\["MCP stdio/HTTP"]
  end

  REST & NFS & S3 & WebDAV & FUSE & MCP --> Storage

  subgraph KiwiFS\["KiwiFS Server"]
  Storage\["Storage Layer"] --> Git\["Git Commit"]
  Git --> Index\["Search Index"]
  Index --> SSE\["SSE Broadcast"]
  end
</Mermaid>

| Protocol     | Use case                            | Example                                           |
| ------------ | ----------------------------------- | ------------------------------------------------- |
| **REST API** | Web frontend, scripts               | `curl localhost:3333/api/kiwi/file?path=index.md` |
| **MCP**      | AI agents (Claude, Cursor)          | `kiwifs mcp --root ~/knowledge`                   |
| **NFS**      | Docker, Kubernetes (native mount)   | `docker run --mount type=nfs,...`                 |
| **S3**       | Backup, data pipelines              | `aws s3 sync s3://knowledge/ /backup/`            |
| **WebDAV**   | Windows mapped drives, legacy tools | Map Network Drive in Explorer                     |
| **FUSE**     | Developer workstations              | `kiwifs mount --remote http://server:3333 ~/kiwi` |

Setup guides for NFS, S3, WebDAV, and FUSE: [Alternate protocols](/guides/alternate-protocols).

## Provenance tracking

Know which agent run produced which content:

```bash theme={null}
curl -X PUT localhost:3333/api/kiwi/file?path=report.md \
  -H "X-Actor: agent:exec_abc" \
  -H "X-Provenance: run:run-249" \
  -d "# Run 249 Report..."
```

KiwiFS injects `derived-from` into the frontmatter automatically. Query later: "show me every page produced by run-249."