flockfsConnect an agent (MCP)
flockfs speaks the Model Context Protocol in two ways: over stdio (flockfs mcp) for local agents,
and over Streamable HTTP at https://<your-server>/mcp for hosted ones. Both expose the same tools
and go through the same permission checks.
Connect a client
Claude.ai and ChatGPT connect through OAuth, so there is no token to copy.
- Claude: Settings → Connectors → Add custom connector, name it "flockfs" and paste
https://<your-server>/mcp. - ChatGPT: turn on Developer mode (Settings → Security and login), then add a plugin at
chatgpt.com/plugins with
https://<your-server>/mcp. Read and write tools need a Business, Enterprise or Edu workspace; other plans may get read-only access.
Claude (or ChatGPT) registers itself and opens flockfs's consent page, where a workspace owner signs
in, picks Read-only or Read & write and clicks Allow. The connection shows up under
Access as an agent token and can be revoked there. These clients connect from their vendor's
servers, so flockfs must be reachable at a public HTTPS URL (a 127.0.0.1 server will not
work; put it behind a TLS reverse proxy or tunnel and set FLOCKFS_PUBLIC_URL=https://<your-server>
if the proxy rewrites Host). Any MCP client that implements the MCP authorization spec works the
same way; see OAuth for remote MCP clients.
Coding agents add the hosted server with one command (OAuth runs in the browser):
claude mcp add --transport http flockfs https://<your-server>/mcp
codex mcp add flockfs --url https://<your-server>/mcp && codex mcp login flockfs
code --add-mcp '{"name":"flockfs","type":"http","url":"https://<your-server>/mcp"}' # VS Code / Copilot
gemini mcp add --transport http flockfs https://<your-server>/mcpCursor: add { "mcpServers": { "flockfs": { "url": "https://<your-server>/mcp" } } } to
.cursor/mcp.json. With a token instead of OAuth, send Authorization: Bearer <token>
(for example claude mcp add ... --header "Authorization: Bearer $FLOCKFS_TOKEN").
Local (stdio), using absolute paths:
claude mcp add flockfs -- "$HOME/.local/bin/flockfs" mcp --url http://127.0.0.1:4317 --token-file "$PWD/data/token"Files are also MCP resources (flockfs://<path>). Claude Desktop config:
{"mcpServers": {"flockfs": {"command": "/Users/me/.local/bin/flockfs",
"args": ["mcp", "--url", "http://127.0.0.1:4317", "--token-file", "/abs/path/data/token"]}}}Another drive: add "--drive", "research" to args (stdio), or use https://<server>/mcp/research
(hosted; bare /mcp is the token's drive, else the default). flockfs setup prints both for its
drive (next.mcpStdio, next.mcpHttp).
Tools
The same tools over stdio (flockfs mcp) and Streamable HTTP (POST /mcp, protocol
2025-06-18, stateless JSON responses; GET returns 405). Hosted MCP authenticates every
call with the API's bearer token and runs through the same permission checks, so a
read-only agent token only reads.
| Tool | What it does |
|---|---|
list | Tree of folders/files with size, text/binary, revision; optional folder. |
read | Text with revision header; images as image content; other binaries as metadata. |
write | Whole file (content or content_base64), creating parents; optional base revision merges. exclusive: true creates only if absent and never replaces existing content. |
edit | Exact unique old_string → new_string (or replace_all); merges with concurrent edits. |
append | Atomic append (creates the file). |
move, delete, mkdir | Move/rename; delete (recursive for folders); mkdir -p. |
search, links, history | Text search; links/backlinks; versions with diffs. search also returns structuredContent {results:[{id,title,url}]}. |
fetch | One file's full text by id (the path from a search result): {id,title,text,url,metadata} as structuredContent and as JSON text. With search, this is the pair ChatGPT deep research and company knowledge use. |
changes | Events after a cursor; wait_seconds (≤ 25) long-polls to react to others. |
lock | Lease a file, a line range (start_line/end_line) or a heading's section before a multi-step change; others' edits there are refused. Expires on its own (ttl_seconds, default 600, max 3600); renew_id extends it. message leaves a note for the holders of overlapping locks; note_id + message leaves a note on one lock or claim. |
unlock, locks | Release by id or all of yours on path; list active locks (who, which lines, why, until when, notes for the holder). |
changed_since_read | Files you read (read/fetch) that someone else changed afterwards, with who and when. Every tool result also carries a one-time heads-up when that happens. Backed by GET /api/timeline/stale. |
claim | Claim a Markdown section by heading id (docs/guide.md#setup) while working on it (a range lock; seconds, reason, message). |
tree | The notes (Markdown and text files) as a tree of headings with ids like docs/guide.md#setup and line ranges; optional folder. See Concept graph. |
mentions | Where a concept (a [[wiki]] target, #tag or defined term; name, id or heading id) is referred to: links and tags, and with unlinked (default true) its name in plain text, with file, line, heading and the line. |
concept | Everything about a concept as one document of live sections: definitions, sections linking to it, tags, mentions, what it links to, and (depth 2-3) related concepts' definitions. Blocks headed ── <relation> · <path>:<start>-<end> · <heading id> (revision N) ──. |
related | Concepts sharing sections with a concept or a file (path), ranked. |
Every tool call is recorded in the drive's timeline (tool, path, sanitized
arguments, outcome, duration), attributed to the verified credential; FLOCKFS_SESSION (stdio) or the
X-Flockfs-Session header (hosted) groups one run. flockfs timeline, the SDK's timeline()/logAction()
and the web app's Activity → Timeline show it.