Skip to content

ctxfs API

The ctxfs server provides REST endpoints under /api/ctxfs and an MCP endpoint at POST /mcp. The managed server listens on the Unix socket ~/.ctxd/local/ctxfs.sock by default.

Check the active URL with:

Terminal window
ctxd endpoint status

The managed Unix socket uses local peer trust. Every TCP HTTP request requires Authorization: Bearer <token>, including loopback. Network clients must use HTTPS with a certificate they trust. REST and HTTP MCP use the same authentication and authorization policy.

OperationEndpointImportant parameters
Stat a pathGET /api/ctxfs/statpath
List a directoryGET /api/ctxfs/lspath,limit
Walk a subtreeGET /api/ctxfs/treeprefix,depth,limit
Match pathsGET /api/ctxfs/globpattern,prefix,limit
Read a fileGET /api/ctxfs/readpath,max_bytes
Read line rangeGET /api/ctxfs/read-linespath,start_line,end_line
Match a regular expressionGET /api/ctxfs/greppattern,prefix,limit,timeout_seconds,cursor
Submit tracker changesPOST /api/ctxfs/submissionsTracker-managed submission payload
MCP JSON-RPCPOST /mcpMCP initialize,ping,tools/list,tools/call

REST and MCP paths use canonical ctxfs paths beneath local-files/<ROOT_ID>/. The CLI resolves human-readable aliases only for folders configured on that client. Other clients use canonical paths.

Terminal window
ctxd files ls Documents
ctxd files glob "Documents/**/*.md" --limit 100
ctxd files read-lines Documents/runbook.md --start 20 --end 40
ctxd files grep "rollback" --prefix Documents --limit 50

Use these CLI commands for normal access. They handle the effective local or network endpoint, endpoint-scoped bearer credential, and folder aliases.

For MCP, configure ctxd-mcp as described in the ctxfs guide, or connect an HTTP-capable MCP client to /mcp on the effective endpoint. HTTP MCP clients need status for initialization and ping and read for tool discovery and calls. The submission endpoint requires submit and enforces the credential’s prefix grants; it is used by the tracker rather than as a general write API.

Directory, tree, glob, and grep responses are bounded by limit. Check the response’s completeness fields before treating a result as exhaustive. Grep uses a 2-second timeout by default; timeout_seconds accepts 0.1 through 60 seconds. A resumable result sets continuation_required and provides both next_cursor and a continuation_hint; repeat the same pattern and prefix with that value as cursor. After repeated timeout stops, increase timeout_seconds or narrow the prefix without restarting from the beginning. Cursors are opaque and become stale if the file being resumed changes. File reads include content identity metadata so a caller can detect changed content.

read accepts at most 5,000,000 bytes. The default is 1,000,000 bytes. Use read-lines when an agent needs only a section of a large file.

  • 400 — invalid path, range, pattern, or limit
  • 401 — bearer credential is missing, invalid, expired, or revoked
  • 403 — the credential lacks the required scope or submission prefix
  • 404 — requested path does not exist
  • 503 — ctxfs is unavailable; check ctxd endpoint status