Skip to main content
AgentFS can run as an MCP (Model Context Protocol) server, exposing filesystem and key-value operations to AI assistants like Claude Desktop.

​
Starting the MCP Server

agentfs serve mcp my-agent
This starts an MCP server that exposes AgentFS tools over stdio.

​
Available Tools

​
Filesystem Tools

ToolDescription
read_fileRead file contents
write_fileWrite file contents
readdirList directory contents
mkdirCreate directory
removeRemove file or directory
renameRename file or directory
statGet file metadata
accessCheck file access permissions

​
Key-Value Tools

ToolDescription
kv_getGet value by key
kv_setSet key-value pair
kv_deleteDelete key
kv_listList all keys

​
Limiting Exposed Tools

For security, you can limit which tools are available: 
# Read-only mode
agentfs serve mcp my-agent --tools read_file,readdir,stat,kv_get,kv_list

# Filesystem only
agentfs serve mcp my-agent --tools read_file,write_file,readdir,mkdir,remove

# Key-value only
agentfs serve mcp my-agent --tools kv_get,kv_set,kv_delete,kv_list

​
Security Considerations

The MCP server gives AI assistants direct access to the AgentFS filesystem. Consider these security practices:
  • Limit tools - Only expose tools the assistant needs
  • Use overlays - Create overlay filesystems instead of giving access to real directories
  • Review the agent database - Check .agentfs/*.db periodically

​
Debugging

Check if the MCP server is working: 
# Run manually to see output
agentfs serve mcp my-agent

# Check if the database exists
ls -la .agentfs/my-agent.db

​
Next Steps

NFS Server

Remote access via NFS

Copy-on-Write Overlays

How isolation works