Agent Filesystem

Agent Filesystem

This plugin connects Codex to AFS as the agent-filesystem MCP server. It uses

a control-plane token, so the server exposes workspace management and

token-management tools rather than file tools for one specific workspace.

Before Acting

• Prefer the agent-filesystem MCP tools for workspace management instead of

shelling out to afs or editing local config by hand.

• Treat workspace deletion and checkpoint restore as destructive. Confirm the

target workspace and checkpoint with the user before calling those tools.

• Do not print full bearer tokens back to the user. If a token tool returns a

token, tell the user where it should be stored and avoid repeating it in later

messages.

• Use Self-managed in user-facing copy for a user-run control plane.

Control-Plane Tools

Use these tools when the agent-filesystem MCP server is connected with a

control-plane token:

• workspace_list: list visible workspaces.
• workspace_get: inspect a specific workspace.
• workspace_create: create a workspace, optionally from a template.
• workspace_fork: fork a workspace into a new workspace.
• workspace_delete: delete a workspace and its data. Confirm first.
• checkpoint_list: list checkpoints for a workspace.
• checkpoint_create: create a checkpoint from live workspace state.
• checkpoint_restore: restore live workspace state from a checkpoint. Confirm first.
• mcp_token_issue: mint a workspace-scoped MCP token for a specific workspace.
• mcp_token_revoke: revoke a control-plane or workspace MCP token by id.

Common Flows

Orient on Available Workspaces

Call workspace_list, then summarize the workspace names, databases, template

slugs, and anything that looks like a likely current target.

Create a Workspace

Ask for a name only if the user has not given one. Prefer lowercase,

hyphen-delimited workspace names. If a template is relevant, pass

template_slug; otherwise create an empty workspace.

Prepare a Workspace-Specific Agent Connection

• Call mcp_token_issue with the workspace name and a clear token label.
• Use workspace-rw for normal file editing, workspace-ro for inspection,

and workspace-rw-checkpoint when the agent should manage checkpoints.

• Tell the user to store the returned token in the target client's secret

mechanism or environment variable, depending on that client's MCP config.

• Use the url returned by mcp_token_issue; it will match the cloud or

local/Self-managed control plane the agent is connected to.

For Codex, prefer an environment-backed token:

[mcp_servers.afs-workspace-name]
url = "<url-returned-by-mcp_token_issue>"
bearer_token_env_var = "AFS_WORKSPACE_TOKEN"

Create a Checkpoint

Call checkpoint_create before risky changes or when the user explicitly asks

for a restore point. Use a short, meaningful checkpoint name when one is given;

otherwise let the server generate one.

Endpoint Configuration

The plugin's MCP endpoint is configured in the plugin root .mcp.json.

Use the cloud endpoint for AFS Cloud:

"url": "https://agent-filesystem.vercel.app/mcp"

Use localhost for a local or Self-managed control plane:

"url": "http://127.0.0.1:8091/mcp"

Key Points

• A control-plane token manages workspaces and can mint workspace tokens.
• A control-plane token does not expose file tools directly.
• File reads and writes require a workspace-scoped token issued for the target

workspace.

• Checkpoints are explicit. Editing files does not automatically create a

checkpoint.

• Redis remains the source of truth for workspaces, manifests, blobs,

checkpoints, and activity.