Connect 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://app.flockfs.com/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://app.flockfs.com/mcp. - ChatGPT: turn on Developer mode (Settings → Security and login), then add a plugin at
chatgpt.com/plugins with
https://app.flockfs.com/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 drive 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. 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://app.flockfs.com/mcp
codex mcp add flockfs --url https://app.flockfs.com/mcp && codex mcp login flockfs
code --add-mcp '{"name":"flockfs","type":"http","url":"https://app.flockfs.com/mcp"}' # VS Code / Copilot
gemini mcp add --transport http flockfs https://app.flockfs.com/mcpCursor: add { "mcpServers": { "flockfs": { "url": "https://app.flockfs.com/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), with the CLI and an agent token saved to a file (create one under Access or in the app's Connect dialog), using absolute paths:
claude mcp add flockfs -- "$HOME/.local/bin/flockfs" mcp --url https://app.flockfs.com --token-file "$HOME/.flockfs/token"Files are also MCP resources (flockfs://<path>). Claude Desktop config:
{"mcpServers": {"flockfs": {"command": "/Users/me/.local/bin/flockfs",
"args": ["mcp", "--url", "https://app.flockfs.com", "--token-file", "/Users/me/.flockfs/token"]}}}Another drive: add "--drive", "research" to args (stdio), or use https://app.flockfs.com/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; PDF, Word (.docx), Excel (.xlsx) and PowerPoint (.pptx) files as their extracted text, labeled (Extracted text of contract.pdf (12 pages)), in pages of lines (offset, limit, default 2,000 lines); 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; for documents their extracted text): {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. |
summarize | What an agent needs to write or refresh a concept's summary note: the current summary and whether it is up to date (or none, and the suggested concepts/<Name>.md), then only the source sections changed since it last changed (all for every one), ending with what to do. concept also starts with the summary. Read-only. |
Documents
read, fetch and search see the text of PDF, DOCX, XLSX and PPTX files, extracted by
the server: headings and paragraphs, tables as Markdown tables, one ## Page N,
## Sheet: name or ## Slide N: title section per page, sheet or slide. The text is
read-only and marked as extracted; to change a document, write a new version with
content_base64. Limits and how extraction works: File storage.
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.