This guide covers the full connection flow: from creating a key to your agent's first authorized call.
1) Decide what your agent actually needs
There are two ways to connect, and most agents only need one:
Reporting only — your agent does its own work elsewhere and just needs to tell Filepad what happened:
events.write ← push activity events
signals:write ← raise findings for the workspace to see
notifications:read ← read and acknowledge its mailbox
Use the Agent Access API (/agent-api/v1) for this. It's a lightweight, one-way reporting channel.
Reading or editing workspace content — your agent needs to search, read, or write artifacts, files, or memory:
artifacts:read
artifacts:write
memory:read
memory:write
Use the MCP endpoint (/mcp) for this. It exposes a governed, scope-limited set of tools over the workspace — the same tool catalog FilepadAI itself uses, filtered to what an external agent is allowed to call.
Only grant the scopes your agent actually needs. A key with artifacts:read only can search and read; it cannot write anything.
2) Create the Agent Access key
In your workspace, go to Agents → Agent Access → New key.
- Name it after the agent or pipeline it belongs to
- Select the scopes from step 1
- Copy the secret — it is shown once
The key is workspace-scoped. It cannot access any other workspace.
3) Authenticate your requests
Every Agent Access and MCP request uses an OAuth bearer token. See the API v1 reference for the full auth flow.
4) Call the API
To report activity (Agent Access API):
POST /agent-api/v1/workspaces/:workspaceId/events
{ "idempotencyKey": "run-42:done", "eventType": "agent.run.completed", "occurredAt": "..." }
To search, read, or edit workspace content (MCP), connect an MCP client to /mcp with your bearer token. The tool list returned to your connection is filtered to the scopes it was granted — for example, a key with artifacts:read sees search and read tools; add artifacts:write to see editing tools as well.
5) Expect approvals on higher-risk writes
Some writes apply immediately; higher-risk ones (editing an existing document, moving or deleting files) may return approval_required instead of applying right away. That means a human needs to review and approve the change in Filepad before it lands. Design your agent to handle that response — poll or wait, don't treat it as a failure.
6) Verify what landed
After a run, check the file tree for new or changed artifacts, and check the Reviews panel for anything still pending approval.
Spot-check the output against your sources. If the result is off, look at the scopes you granted, any operating notes you left for the agent, and its recent activity — those are the most common sources of drift.