...
Sign Up Free
Log In

Agents: start here

View as Markdown llms.txt

Integrating Filestack as an AI agent? Start here. These steps take you from setup to your first upload, transformation, and delivery, with links to the full reference at every stage.

  1. Install the Filestack plugin
  2. Get credentials
  3. Handle credentials safely
  4. Pick the tool for the job
  5. Use the machine-readable docs
  6. Build

1. Install the Filestack plugin

The Filestack plugin runs in Claude Code and Cursor. Both editors run the same local MCP server, skills, and slash command from one repository.

19MCP tools
5skills
1slash command

Add the Filestack marketplace, then install the plugin:

/plugin marketplace add https://github.com/filestack/filestack-claude-plugin.git
/plugin install filestack-claude-plugin@filestack-plugin

Restart Claude Code. Skills and the MCP server load at session start.

Install Filestack from the Cursor plugin marketplace. Cursor reads .cursor-plugin/plugin.json from the same repository and runs the same MCP server, skills, and slash command for the Agent.

# Plugin repository
https://github.com/filestack/filestack-claude-plugin

Manual install

The MCP server runs on Node.js:

git clone https://github.com/filestack/filestack-claude-plugin.git
cd filestack-claude-plugin/mcp && npm install && npm run build

If your runtime does not load plugins, call the REST APIs directly and use the machine-readable docs.

2. Get credentials

The plugin runs on a built-in demo API key until FILESTACK_API_KEY is set. The demo key has limited functionality and is for building and testing only.

  • If the user has a Filestack account, ask for their API key. It is in the Developer Portal. Ask for the app secret only if the task needs policy signing or signed URLs.
  • If they don’t, send them to filestack.com/signup-free to create a free account.

Set the variables before starting the editor, then restart it:

export FILESTACK_API_KEY=your_api_key
export FILESTACK_APP_SECRET=your_app_secret # only needed for security tools
Variable Required Used by
FILESTACK_API_KEY No (demo key used if unset) All file operation and transformation tools
FILESTACK_APP_SECRET Security tools only filestack_sign_policy, filestack_generate_signed_url

3. Handle credentials safely

  • Store the app secret in a local .env file or the server environment. Do not print it in chat.
  • Confirm that version control ignores .env.
  • Never put the app secret in browser or native-app code. The API key is public and appears in client code; read it from an environment variable (for example import.meta.env.VITE_FILESTACK_API_KEY) instead of hardcoding it.
  • The MCP server signs policies on the local machine. The app secret is not sent to Filestack.
  • When the app has security enabled, every request needs a policy and signature. Generate them on the server. Intelligence tasks need convert in the policy’s call list; workflows need convert and runWorkflow.

Reference: Security Policies.

4. Pick the tool for the job

Task MCP tool Reference
Upload a local file or remote URL filestack_upload Uploading
Ingest a remote URL into storage filestack_store_url File API
Read file metadata filestack_retrieve File API
Delete a file filestack_delete File API
Build a transformation URL (no API call) filestack_transform_url Processing API
Apply a transformation and store the result filestack_transform_apply Processing API
List supported transformations filestack_list_transforms Processing Engine
Tag, moderate, caption, OCR, or detect documents filestack_analyze Intelligence
Convert documents (DOCX, PPTX, XLSX, PDF, and more) filestack_convert_document Processing API
Transcode video (async) filestack_convert_video
filestack_video_status		 Video and Audio Processing API
Bundle up to 100 files as a ZIP filestack_zip_files Processing API
Screenshot a web page filestack_screenshot_url Processing API
Create and sign a policy, or a signed URL filestack_generate_policy
filestack_sign_policy
filestack_generate_signed_url 		Security Policies
Virus scan, phishing detection, video intelligence filestack_run_workflow Workflows
Verify an incoming webhook, or sign a test payload filestack_verify_webhook_signature
filestack_sign_webhook_payload		 Webhooks

Transformations chain left to right in the CDN URL. Put processing tasks (resize, crop, enhance) before output:

https://cdn.filestackcontent.com/resize=width:800,height:600/output=format:webp/abc123XYZ

Skills

Skills load automatically when the conversation or code matches their triggers.

Skill Loads when
filestack-sdk-integration Code imports filestack-js or filestack, or calls client.upload( or
client.picker(
filestack-error-diagnosis A Filestack endpoint returns 401, 403, 404, or 429, or an error body appears
filestack-webhook-setup Code handles FS-Signature, FS-Timestamp, or events such as fp.upload
filestack-intelligence The task involves tagging, moderation, OCR, captioning, or sentiment
filestack-workflow-design The task involves a multi-step pipeline, a workflow UUID, or fs.workflow

Slash command

/filestack-transform abc123XYZ resize to 800x600 and convert to webp

5. Use the machine-readable docs

  • llms.txt: every documentation page with a one-line description. Read it first.
  • Root llms.txt: the wider Filestack product line, pricing, and case studies.
  • Use Copy page or View as Markdown at the top of this page to get it as Markdown.

6. Build

Troubleshooting

Problem Fix
Tools return “API key not configured” Set FILESTACK_API_KEY and restart the editor
Security tools return “App secret not configured” Set FILESTACK_APP_SECRET and restart the editor
Skills do not appear after install Restart the editor. Skills load at session start
filestack_upload fails for a local file Use an absolute path or one relative to the working directory
filestack_transform_apply returns 403 Check that the API key has processing permissions in the Developer Portal
Signed URLs return 403 Confirm the policy has not expired and its call list covers the operation
1. Install the Filestack plugin
Manual install
2. Get credentials
3. Handle credentials safely
4. Pick the tool for the job
Skills
Slash command
5. Use the machine-readable docs
6. Build
Troubleshooting