docs/mcp-setup.md

MCP Setup

Connect agent-fs to Claude Code, Cursor, Codex, and other MCP clients.

Connect agent-fs to any MCP-compatible AI assistant (Claude Code, Cursor, Windsurf, etc.).

Claude Code

Add to your .mcp.json (project-level or ~/.claude/.mcp.json for global):

json

{
  "mcpServers": {
    "agent-fs": {
      "command": "agent-fs",
      "args": ["mcp"],
      "env": {
        "AGENT_FS_API_URL": "http://localhost:7433",
        "AGENT_FS_API_KEY": "your-api-key"
      }
    }
  }
}

Prerequisites: The agent-fs daemon must be running (agent-fs daemon start). The agent-fs mcp command is a stdio-to-HTTP proxy that connects to the daemon's /mcp endpoint.

With embeddings

To enable semantic search, configure an embedding provider on the daemon (via ~/.agent-fs/config.json or environment variables). The daemon initializes embeddings at startup and makes them available to both REST and MCP clients.

Supported providers: OPENAI_API_KEY (OpenAI), GEMINI_API_KEY (Google Gemini), or local (configured in ~/.agent-fs/config.json). Local runs nomic-embed-text-v1.5 on llama.cpp or EmbeddingGemma 2 on transformers.js. Set EMBEDDING_PROVIDER to pick one explicitly. It takes priority over the API key variables.

Cursor

Add to your Cursor MCP settings (Settings > MCP Servers):

json

{
  "agent-fs": {
    "command": "agent-fs",
    "args": ["mcp"],
    "env": {
      "AGENT_FS_API_URL": "http://localhost:7433",
      "AGENT_FS_API_KEY": "your-api-key"
    }
  }
}

Generic MCP Client (stdio transport)

agent-fs uses stdio transport. Spawn the process and communicate via JSON-RPC over stdin/stdout:

bash

agent-fs mcp

The server advertises tools via the standard MCP tools/list method.

Available Tools

Content Operations

Tool	Description
`write`	Write or overwrite a file. Creates a new version. Use `expectedVersion` for optimistic concurrency.
`cat`	Read file content with optional pagination via `offset`/`limit`.
`edit`	Replace a specific string in a file (surgical find-and-replace).
`append`	Append content to the end of an existing file.
`tail`	Read the last N lines of a file.

Tool	Description
`ls`	List immediate children of a directory. Path defaults to `/` (root).
`stat`	Get file metadata without reading content.
`tree`	Recursively list all files and directories. Path defaults to `/` (root). Use `depth` to limit.
`glob`	Find files by pattern. `.md` matches root only; `/.md` matches recursively. Case-sensitive.
`find`	Find files by approximate name. Ignores case and accents and takes words in any order. When no file has every word as typed, letters can be skipped. Best match first.

File Management

Tool	Description
`rm`	Delete a file. Removes from S3, cleans up FTS5 and embeddings.
`mv`	Move or rename a file. Preserves version history.
`cp`	Copy a file using server-side S3 copy.

Version Control

Tool	Description
`log`	Show version history for a file.
`diff`	Show the diff between two versions of a file.
`revert`	Revert a file to a previous version. Creates a new version with the old content.

Search

Tool	Description
`grep`	Regex search across file content via FTS5 index.
`fts`	Full-text keyword search across all files using FTS5 tokens.
`search`	Semantic search using natural language (requires embedding provider).

Maintenance

Tool	Description
`recent`	Show recent activity. Filter by path prefix and time window.
`reindex`	Re-index files with failed or missing FTS5/embedding entries.

Comments

Tool	Description
`comment-add`	Add a comment to a file. Supports line ranges and threading.
`comment-list`	List comments on a file with inline replies. Filter by path, `pathPrefix`, resolved state, or parent.
`comment-get`	Get a single comment by ID with all replies.
`comment-update`	Update a comment's body (author only).
`comment-delete`	Soft-delete a comment (author only).
`comment-resolve`	Resolve or reopen a root comment.
`drive-members`	List the active drive's member emails and display names.

Favorites

Favorites are per user: the tools act on the authenticated user's own stars in the active drive.

Tool	Description
`favorite-add`	Star a file or folder.
`favorite-remove`	Remove your star from a file or folder.
`favorite-list`	List your favorites in the active drive.

Identity & Member Management

Tool	Description
`whoami`	Get current user identity, org memberships, and drive roles. Lists only drives you're an explicit member of.
`member-list`	List members of the current org, or of a drive in the current org via `driveId`.
`member-invite`	Invite an existing agent-fs user to the current org by email. Optional `drives: [{ driveId, role }]` grants exactly those drives; omitted, the user gets the default drive with the org role. Grants only raise: the returned `role` and `drives` are what they hold afterwards.
`member-add`	Add an existing org member to a drive in the current org (`email`, `driveId`, `role`). Raise-only: a role they already hold is never lowered, and the result carries the role they end up with. To lower it, use `member-update-role`.
`member-update-role`	Update a member's org role, or drive role via `driveId`.
`member-remove`	Remove a member from the current org (cascades to drives), or from one drive via `driveId`.

Member tools are admin-gated, mirroring the HTTP member routes: org-scoped calls require org admin; drive-scoped calls require drive admin or admin of the owning org. A driveId must belong to your active org — drive IDs from other orgs return "not found", and authorization runs before any email lookup, so non-admins can't probe whether an account or drive exists.

Which Search Tool Should I Use?

agent-fs has three search tools for different use cases:

Tool	Use When	Example
`grep`	You know the exact text or pattern	`grep --pattern "TODO"`
`fts`	You know keywords but not exact text	`fts --query "authentication middleware"`
`search`	You want to find by meaning/concept	`search --query "how does auth work?"`

`grep` is fastest — it uses regex against the FTS5 index. Use for exact strings, patterns, variable names.

`fts` is keyword-based full-text search. Use when you know relevant terms but not the exact phrasing. Supports FTS5 query syntax (AND, OR, NOT, phrases).

`search` is semantic/vector search. Use when you want to find files by meaning, not keywords. Requires an embedding provider (OpenAI, Gemini, or local). Local runs nomic-embed-text-v1.5 on llama.cpp or EmbeddingGemma 2 on transformers.js. Best for questions like "files related to user authentication" where keyword matching would miss relevant results.

Environment Variables

Variable	Description	Required
`AGENT_FS_API_URL`	Server URL (e.g., `http://localhost:7433`)	For remote mode
`AGENT_FS_API_KEY`	API key for authentication	For remote mode
`AGENT_FS_HOME`	Data directory (default: `~/.agent-fs`)	No
`OPENAI_API_KEY`	OpenAI API key for embeddings	For semantic search
`GEMINI_API_KEY`	Google Gemini API key for embeddings	For semantic search

Troubleshooting

"No embedding provider configured"

Semantic search (search tool) requires an embedding provider. Set OPENAI_API_KEY or GEMINI_API_KEY in your MCP config's env block, or configure a provider in ~/.agent-fs/config.json.

"Cannot connect to agent-fs"

The daemon must be running. Start it with agent-fs daemon start, or set AGENT_FS_API_URL to point to a remote server. Default port is 7433.

Tools not appearing

Restart your MCP client after updating the config. Check that agent-fs is in your PATH (which agent-fs).