Agent Access overview | Filepad Docs

Agent Access lets external agents operate against a Filepad workspace without becoming the main Filepad runtime. The agent gets scoped access to real files: instructions, skills, memory, sources, uploads, artifacts, and reviewed automation notes.

How it works

A workspace admin creates an Agent Access key in the workspace.
The key is granted narrow scopes such as env:read or artifacts:write.
The external agent signs every /agent-api/v1 request with HMAC-SHA256.
Filepad validates the signature, checks scopes, and serves real workspace file data.

Agent keys are workspace-scoped. A key for workspace A cannot access workspace B.

What agents can do

Read

Inspect the canonical environment folders
Read the file tree and supported text/Markdown content
Discover skills/*.md files as reusable prompts/capabilities
Search indexed workspace content
Read visible files under memory/ through the file API

Write safely

Create new note artifacts under artifacts/
Create reviewable edit proposals for supported editable files
Push activity events into Filepad

Agent Access v1 does not directly mutate .filepad/, agents/, skills/, memory/, sources/, uploads/, or automations/. Supported file edits are submitted as reviewable proposals.

Scopes

Scope	What it unlocks
`env:read`	Environment summary, file tree, supported file content, search, and prompt/resource discovery
`artifacts:write`	Create note artifacts under `artifacts/`
`files:propose`	Create reviewable edit proposals
`memory:read`	Reserved for future memory-specific read surfaces
`events.write`	Push activity events

MCP tools

Use the published @filepad/mcp-server package when your agent supports MCP. It runs as a local stdio MCP server and delegates every tool call back to Agent Access, so the same scopes, hidden-file rules, proposals, and audit trail apply.

{
  "mcpServers": {
    "filepad": {
      "command": "npx",
      "args": ["-y", "@filepad/mcp-server@latest"],
      "env": {
        "FILEPAD_BASE_URL": "https://app.filepad.ai/api",
        "FILEPAD_WORKSPACE_ID": "ws_...",
        "FILEPAD_AGENT_KEY_ID": "ik_...",
        "FILEPAD_AGENT_SECRET": "..."
      }
    }
  }
}