Skip to main content

Building with FileSpin from Claude Code, Codex and Cursor

Set up the FileSpin plugin for coding agents so they look up exact FileSpin API and image URL syntax instead of guessing, write code against your account's real fields and CDN host, and upload local files and folders to FileSpin.

Coding agents such as Claude Code, Codex and Cursor write plausible code fast. With an API they've only seen in training data, plausible isn't enough: a FileSpin image URL with a guessed parameter looks right and fails in production. This guide shows how to give your agent the FileSpin docs, API reference and your own account as tools, so the code it writes works the first time.

If you use FileSpin from a chat assistant to manage assets rather than to write code, see Using FileSpin within an AI Agent instead.

Building with FileSpin from a coding agent

What you get​

The FileSpin plugin installs three things in your coding agent:

PartWhat it does
The FileSpin MCP server (https://mcp.filespin.io/mcp)Tools that read these developer docs and API reference, read your FileSpin account, and upload files. You sign in with your FileSpin account; the agent never needs your API key.
The filespin-developer skillMakes the agent look up every FileSpin endpoint, parameter and URL option before writing code, carry over the documented defaults and limits, cite the page it used, and keep API keys out of code.
The filespin-upload skillUploads files and folders from your computer when you ask, straight from your disk to your FileSpin storage.

The tools a coding agent uses most:

ToolUse it for
search_api_operationsFind the endpoint for a task ("upload a file", "add assets to a collection").
get_api_operationThe exact method, path, parameters, request body, responses and auth of one endpoint.
search_developer_docsAnything that isn't one endpoint: image URL syntax, video playback, widgets, webhooks, limits, guides.
get_doc_pageRead a whole docs page as markdown.
get_account_info, get_schemas, search_assets, get_thumbnailYour plan and addons, your metadata field names, real asset IDs, and your CDN host.
create_upload_url, complete_upload, get_upload_statusUpload local files (used by the filespin-upload skill).

The docs tools are read-only. The account and upload tools act as you, with your FileSpin role's permissions.

Install and sign in​

Claude Code​

Run these one at a time inside Claude Code, pasting each command on its own. Pasted together, they land in a single prompt and Claude Code rejects them as an invalid marketplace source.

  1. Add the marketplace:

    /plugin marketplace add FileSpin-io/filespin-agent-plugin

  2. Install the plugin:

    /plugin install filespin@filespin

  3. Run /mcp, choose filespin, and sign in to FileSpin.

Or install from your terminal, outside Claude Code:

claude plugin marketplace add FileSpin-io/filespin-agent-plugin
claude plugin install filespin@filespin

Codex​

codex plugin marketplace add FileSpin-io/filespin-agent-plugin

Then run codex, open /plugins, install filespin, and start a new session.

Cursor​

Use the Add to Cursor link on the MCP server page. Cursor asks you to sign in to FileSpin on first use.

Check it works​

Ask:

Which FileSpin plan and addons does my account have, and what metadata fields do my schemas define?

The agent should call get_account_info and get_schemas and answer from your account. If it says it has no FileSpin tools, see Troubleshooting.

Let the agent look things up​

The filespin-developer skill makes the agent follow a lookup loop before it writes FileSpin code:

  1. search_api_operations to find the endpoint for the task;
  2. get_api_operation for its exact parameters, body and responses;
  3. search_developer_docs for everything else, such as image URL options, video, webhooks and limits;
  4. get_doc_page when a search snippet isn't enough.

It then writes the code with the names the docs give, and cites the page it used.

Prompts that work well:

  • "Using the FileSpin docs, write a function that uploads a file and returns the asset ID."
  • "What's the FileSpin image URL for a 400×400 face crop as WebP? Cite the docs page."
  • "Look up how FileSpin webhooks retry, and make my receiver safe to call twice."

Prompts to avoid:

  • "Just write it, you know the API." The skill tells the agent not to work from memory. Asking it to skip the lookup gives you the guessing this setup exists to prevent.

If an answer has no cited page, ask "Which FileSpin docs page is that from?". A correct answer can always point to one.

Code against your real account​

Code written with placeholder values (your-cdn.example.com, my_field, ASSET_ID) breaks when you run it. The agent can read your account so examples work straight away:

Ask forThe agent usesSo that
Your CDN hostget_thumbnail on one of your assetsImage and video URLs use your host, not a placeholder
Your metadata fieldsget_schemasCode reads and writes your exact field names
Real asset IDssearch_assetsExamples and tests run against real assets
Your plan and addonsget_account_infoIt checks an addon is enabled before building on it (for example on-demand images or background removal)

These tools read your data. The skill tells the agent to ask before it changes anything in your account (uploads, metadata updates, shares).

Keep keys out of code​

There are two kinds of credentials, and they never mix:

  • The agent signs in to the MCP server with OAuth when you run /mcp (or on first use). It doesn't need, and shouldn't be given, an API key.
  • Your application calls the FileSpin API with an API key in the X-FileSpin-Api-Key header, server side only. The skill writes code that reads it from configuration, such as os.environ["FILESPIN_API_KEY"] or process.env.FILESPIN_API_KEY, never from a literal.

Create API keys in the FileSpin Dashboard. Don't paste a real key into the chat: the agent doesn't need it, and the conversation isn't the place to keep it.

Upload local files​

Ask in plain words:

Upload ~/Desktop/spring-shoot to FileSpin and add the files to the "Spring 2026" collection.

The filespin-upload skill:

  • Uploads only what you asked for. It skips hidden files and OS clutter (.DS_Store, Thumbs.db), never uploads keys or credentials (.env, *.pem, ~/.ssh/) unless you name that exact file, and asks first before more than 20 files or 1 GB.
  • Sends each file straight to your FileSpin storage. The agent gets a short-lived upload link per file and runs curl on your machine. Your files never pass through the model or the MCP server, so any file type and size up to your plan's limit works.
  • Keeps each file's folder path. FileSpin stores where the file came from (your home folder written as ~, for example ~/Desktop/spring-shoot/hero.jpg) and which agent uploaded it. You can then find the file in FileSpin by any word of its folder names: searching spring finds files under spring-shoot/. The asset page shows it under Uploaded from.
  • Confirms the result. It waits until each upload is ready and tells you which files are in FileSpin and which failed, and why.

Good to know:

  • Each upload link works for one file, for about 15 minutes. If one expires, the agent asks for a new one.
  • Codex: depending on your sandbox settings, Codex may block network access for the commands it runs. Approve the curl command, or allow network access for the session.
  • Windows PowerShell: curl there is an alias for Invoke-WebRequest. The agent should run curl.exe, which ships with Windows 10 and later.
  • Chat-only assistants (Claude Desktop's chat, claude.ai, ChatGPT) can't read your files. Upload from the FileSpin Dashboard instead.

Worked examples​

A responsive product image​

Write a React component that shows a FileSpin product image responsively, in WebP, at 400, 800 and 1200 px wide. Use one of my real assets.

The agent looks up the on-demand image URL syntax for resizing and formats with search_developer_docs, takes your CDN host from get_thumbnail on an asset it found with search_assets, and writes a srcSet with the documented parameters, citing the page. For the background, see Responsive Product Images.

Upload from your app​

Add an endpoint to my Express server that accepts a file from the browser and uploads it to FileSpin with a "campaign" metadata field.

The agent finds the upload endpoint with search_api_operations, reads its exact form fields and host with get_api_operation (uploads go to a different host from the rest of the API), checks that campaign is a field in your schema with get_schemas, and reads the API key from process.env.FILESPIN_API_KEY.

A webhook receiver​

Write a Flask route that receives FileSpin file-processed webhooks and caches the asset's CDN URLs.

The agent reads the webhook events, payload fields and retry behaviour from the docs and builds the handler to match, including handling the same event twice. See Webhooks.

Upload a folder of product shots​

Upload ~/Downloads/SKU-1042 to FileSpin, set metadata sku=1042 on each file, and add them to a new collection called "SKU 1042".

The agent creates the collection, uploads the files with the filespin-upload skill, and confirms each one is ready. Afterwards, searching for 1042 in FileSpin finds them by their folder name.

Troubleshooting​

SymptomFix
... is not a valid GitHub owner/repo shorthand when adding the marketplaceBoth install commands were pasted at once. Paste /plugin marketplace add ... on its own, then /plugin install filespin@filespin.
The agent says it has no FileSpin toolsThe MCP server isn't signed in. In Claude Code run /mcp, choose filespin and sign in. In Codex, start a new session after installing.
The agent writes FileSpin endpoints or URL options without looking them upAsk it to "look this up in the FileSpin docs and cite the page". Check the plugin is installed and enabled.
curl fails with 403 during an uploadThe upload link expired or the file changed after the link was made. The agent requests a new link for that file.
An upload reports checksum_mismatchThe file's MD5 was computed from a different file or version. The agent recomputes it and uploads again.
An upload can't connect from CodexCodex's sandbox may be blocking network access. Approve the command or allow network access.