Agents

Pick the way in that matches what your agent can do. In every case, a person owns the wallet and approves what the agent may do, and the agent never holds the wallet key.

Agent	What it can do	Way in
Local agent, such as Claude Code, Codex, or Cursor	Run a shell, keep files, and open pages for you	Plugin, or CLI and agent skill
Cloud agent, such as a coding agent in a hosted sandbox	Run a shell, but its files are gone when the session ends	CLI with a key from secrets
Browser agent	Read and use web pages in the browser that holds your wallet	fil-app's WebMCP tools
Chat app with connectors, such as Claude or ChatGPT	Call remote tools	MCP server, read-only

Retrieve and verify compares what each way can store, retrieve, and check.

Local agents

In Claude Code and Codex, install the fil plugin. It adds the agent skill and the read-only MCP server in one step. In Claude Code:

claude plugin marketplace add hugomrdias/fil
claude plugin install fil@fil

In Codex:

codex plugin marketplace add hugomrdias/fil
codex plugin add fil@fil

The plugin follows the Agent Plugins format, so other agents that support it can load it from the repository's plugins/fil directory.

In other agents, install the agent skill. It tells the agent when to use fil, the workflow, and the rules, and points it to the CLI's own help, which always matches the installed version:

npx skills add https://fil-app.hugomrdias.dev

npx skills add hugomrdias/fil installs the same skill from GitHub. Agents that support agent skills discovery find it at /.well-known/agent-skills/index.json.

The agent runs the CLI with npx -y @hugomrdias/fil, which needs Node.js 24 or newer. To install it instead, run npm install -g @hugomrdias/fil. Then fil skills install installs the copy of the skill that matches the installed CLI.

The first fil login asks you to approve the agent's key.

Cloud agents

A cloud agent has a shell, so it uses the same skill and CLI as a local agent. It has no browser to open for you, and its disk is gone when the session ends. fil login saves the session key on that disk, so each session would ask you to approve a new key.

Give the agent a key that outlives the session instead:

On the fil-app session keys page, generate a session key, authorize it, and export it.
In the agent's environment settings, add the key as the secret FIL_SESSION_KEY, and your wallet address as FIL_ROOT_ADDRESS.

fil then skips fil login, and fil status confirms the key works. The key cannot move funds, and it expires. Revoke it on the same page to stop the agent. Never paste the key into a chat.

fil ls and fil operations read a local database, which a new session starts without. Find stored content shows how to look it up by wallet.

Browser agents

fil-app registers WebMCP tools. A browser agent can prepare a setup request without building a URL, and read the account, its data sets and pieces, and its session keys. The tools never sign anything, and they describe themselves to the agent. Web app lists them. WebMCP is an early preview that works in Chrome 149 and later. Without it, the agent opens a setup link.

A browser agent cannot run the CLI. You can store files from the dashboard's upload page while it watches, and a folder's link verifies in the browser.

MCP server

fil-api's MCP server gives any agent read-only tools for storage providers, data sets, pieces, Filecoin Pay rails, and session keys, on mainnet and calibration. It uses Streamable HTTP and needs no authentication. It cannot store or delete content.

https://fil-api.hugomrdias.dev/mcp

The fil plugin adds it in Claude Code and Codex. To add the server alone, add-mcp writes it into the configuration of Claude Code, Codex, Cursor, VS Code, and about 20 other agents:

npx -y add-mcp https://fil-api.hugomrdias.dev/mcp

It asks which agents to configure, and adds the server to the current project. Add -g to add it for your user instead.

Claude Code and Codex also add it with their own commands:

claude mcp add --transport http fil-api https://fil-api.hugomrdias.dev/mcp
codex mcp add fil-api --url https://fil-api.hugomrdias.dev/mcp

In the Claude and ChatGPT apps, add the URL as a custom connector. API and MCP lists the tools.

Approve the agent's key

The agent never holds the wallet key. It gets a session key instead, and the wallet owner approves it:

The agent runs fil login. It gets a login_pending error with an approval link, and relays the link to you.
You open the link, connect your wallet, and review the request on the fil-app setup page. Approve the session key, the Warm Storage approval, and a USDFC deposit if the page asks for them.
The agent runs fil login --check to confirm, then fil put. --check never makes a new key, so it can't replace the one you approved.

When the account runs low, fil status and fil put return insufficient_funds with a prefilled funding link for you. To stop the agent, revoke its key on the fil-app session keys page.

Discovery files

This site describes itself to agents:

Path	Contents
`/llms.txt`	An index of these docs in Markdown, from llmstxt.org
`/llms-full.txt`	Every docs page in one Markdown file
`/.well-known/api-catalog`	Links to fil-api's OpenAPI document, reference, and MCP server, as an RFC 9727 API catalog
`/.well-known/integrations.json`	The REST API, the MCP server, and the CLI, with what each needs to authenticate, for integrations.sh
`/.well-known/mcp/server-card.json`	The MCP server card, also at `/.well-known/mcp-server-card`
`/.well-known/agent-skills/index.json`	The agent skills index, with the `fil` skill
`/sitemap.xml`	Every page, also linked from `/robots.txt`

Every docs page also has a Markdown version. Add .md to the path, such as /docs/cli.md, or send Accept: text/markdown:

curl -H 'Accept: text/markdown' https://fil-app.hugomrdias.dev/docs/cli

A request that accepts only Markdown gets a Markdown answer from every page. A missing page returns 404 with links to llms.txt and the sitemap. An explorer or dashboard page, which has no Markdown version, returns 406.