Using FileSpin within an AI Agent
How MCP-compatible AI agents connect to FileSpin, discover 33 tools and 36 workflow recipes, and execute end-to-end media operations through natural language -- setup, authentication, tool patterns, and real-world examples.
FileSpin offers three automation paths: AI agents for ad-hoc, complex workflows through natural language; workflow engines for repeatable, visual pipelines operations teams build without engineering; and REST APIs for custom, high-throughput integrations. This guide covers the first path -- AI agents.
FileSpin is an AI-native digital asset management platform used by eCommerce retailers, event producers, attractions operators, and media companies to manage, transform, and deliver assets autonomously. One of the most powerful ways to interact with FileSpin is through AI agents -- Claude, ChatGPT, Mistral or any MCP-compatible client -- that connect to the platform via the Model Context Protocol and execute complex media workflows through natural language.
Instead of learning API endpoints and building integration code, your team describes what they need: "Tag all new arrivals by SKU, remove backgrounds, and send a review link to the buying team." The agent discovers FileSpin's capabilities, chains the right operations together, and executes the entire workflow end-to-end.
This guide covers the architecture, setup, available capabilities, and real-world workflow patterns so your engineering team can evaluate and integrate FileSpin's MCP server.
What is the Model Context Protocol (MCP)?
MCP is an open standard that lets AI agents discover and use external tools. Instead of hard-coding API calls or building custom plugins, an MCP server advertises its capabilities -- tools and prompt templates -- and any compatible AI agent can discover and invoke them at runtime.
FileSpin's MCP server exposes the full FileSpin platform as 33 tools and 36 prompt templates across 11 workflow categories. The agent connects to FileSpin MCP, authenticates via OAuth2, and has access to every operation your FileSpin account role permits.
Key concepts
| Concept | What it means |
|---|---|
| Tools | Atomic operations (search, upload, tag, share, transform, etc.) callable by any MCP client. 33 are active. |
| Prompts | Multi-step workflow recipes that chain tools together. 36 are registered across 11 categories. |
| OAuth2 Authentication | Standard OAuth2 flow. The agent authenticates as a FileSpin user and inherits that user's account role and permissions. |
| Asset Shares | Branded, hosted web pages for external distribution with download controls, approval workflows, and analytics. |
| Collections | Internal organizational groups for team collaboration and bulk operations. |
| Addons | Platform capabilities (face recognition, auto-tagging, background removal) that gate certain tools; checked at runtime. |
How it works
When an AI agent connects to the FileSpin MCP server, the interaction follows three phases: the agent discovers available capabilities, executes a chain of tool calls to fulfill the user's request, and returns the result.
The agent handles all orchestration -- deciding which tools to call, in what order, with what parameters -- based on the user's natural language request. The MCP server translates each tool call into the corresponding FileSpin REST API request.
Step 1: Configure the FileSpin MCP server
FileSpin The MCP URL: https://mcp.filespin.io/mcp
Claude Desktop
Add FileSpin to your Claude Desktop via Settings -> Connectors.
ChatGPT and other MCP clients
Any MCP-compatible client can connect to the FileSpin MCP server. Add the MCP server using standard connector option.
Step 2: Authentication and permissions
The FileSpin MCP server uses standard OAuth2 authentication. When the agent connects, it authenticates through the OAuth2 flow (i.e. a broser window opes and user is asked to authenticate FileSpin MCP by logginh into FileSpin). The agent receives a token scoped to the authenticating user's FileSpin account role after successful login.
What the agent can do is determined entirely by the FileSpin account role of the authenticated user. If the user has read-only access, the agent can only read. If the user has full admin access, the agent can upload, tag, share, and manage assets.
This means:
- No separate API key scoping -- the agent inherits the user's existing permissions.
- Audit trails -- every action the agent takes is logged under the authenticated user's account.
- Role-based control -- restrict what agents can do by assigning appropriate FileSpin roles to the users who connect agents.
Create a dedicated FileSpin user account for your AI agent with the minimum role required for its intended workflows. This gives you a clean audit trail and precise permission control.
Note that complete purging of assets is not available via MCP.
Let the AI get you started
The quickest way to get started is to let the AI Agent such as Claude or ChatGPT guide you in using FileSpin MCP. When FileSpin MCP is added to the AI Agent, it provides the AI Agent with comprehensive information to guide you in using it. Start with the prompt:
Help me get started with FileSpin MCP, walk me through the prompts and workflows I can do - starting with how to login, find assets and have them reviewed and finalised
Available tools (30+ tools)
The FileSpin MCP server exposes a comprehensive set of tools that agents can call directly. These are atomic operations -- the building blocks that agents compose into workflows. They are a intelligence layer on top of FileSpin REST APIs that provide securely mediate the AI Agent's calls to FileSpin API.
| Category | Summary |
|---|---|
| Asset management | Search and inspect assets, upload new files, update metadata (single or bulk), discover schemas, and check account capabilities. |
| Image transformation | Generate resized/cropped image variants, create social-platform formats, and apply image or text watermarks. |
| AI and addons | Find related photos using face search and retrieve AI-generated labels with confidence scores. |
| Sharing and distribution | Create, list, and delete branded share pages; track analytics and approvals; and reuse share templates. |
| Collections | Create and search collections, manage included assets, and generate ZIP download links. |
| Video | Transcode videos, create trimmed/custom clips, and retrieve streaming URLs. |
| Delivery | Generate CDN view URLs and signed download URLs for assets. |
Prompt templates -- pre-built workflow recipes
Prompt templates are the most powerful feature of the FileSpin MCP server. They are multi-step workflow recipes that guide the agent through complex operations. The agent discovers them automatically, and when invoked, receives a structured message that tells it exactly which tools to call and in what order.
There are 36+ prompt templates across 11 categories:
Industry-specific workflows
| Workflow | Summary |
|---|---|
| E-commerce (2 prompts) | Run end-to-end product-image workflows, including tagging, social output generation, review sharing, and marketplace-ready sizing. |
| Events (2 prompts) | Automate event media workflows with speaker/sponsor discovery, session tagging, social crops, and branded approval shares. |
| Attractions (2 prompts) | Support attraction photo operations with guest face discovery, preview watermarking, and branded gallery sharing. |
Platform workflows
| Workflow | Summary |
|---|---|
| Social Media (3 prompts) | Generate platform-specific image sizes, apply logo watermarks, add text watermarks. |
| AI Workflows (4 prompts) | Face search by asset or URL, find addon-processed assets, retrieve AI auto-tags with confidence scores. |
| Video Processing (2 prompts) | Transcode with existing-conversion check (avoids redundant processing), create custom clips with trimming. |
| Creative (2 prompts) | Face-centered profile pictures at multiple sizes, responsive hero images for desktop/tablet/mobile. |
| Branded Shares (8 prompts) | Press kits, branded galleries, video showcases, review/approval pages, template-based shares, analytics review, approval status checks, expired share cleanup. |
| Collections (3 prompts) | Save search results to a collection, download collection as ZIP, update collection membership. |
| Administration (4 prompts) | Bulk tag photoshoot assets, audit metadata completeness, find assets needing review, standardize inconsistent metadata values. |
| Content Creation (4 prompts) | Save HTML reports, CSV exports, Markdown docs, and metadata CSV exports to FileSpin. |
How prompts work
When a user says "Process all product images from the summer shoot", the agent matches this to the prompt template and receives:
Process product images matching "summer shoot" uploaded recently:
1. Search FileSpin for images matching "summer shoot".
2. Use get_schemas to get the schema ID, then tag_assets_bulk with: campaign="Summer Campaign",
category="product", status="ready".
3. Use get_social_media_images to generate Instagram feed and Facebook post versions.
4. Use create_share to create a branded review page with allow_approval enabled for the buying team.
Give me the share URL and a summary of assets processed.
The agent then executes each step, calling the appropriate tools in sequence, handling responses, and reporting back to the user.
Tool selection patterns
When agents compose multi-tool workflows -- whether guided by prompts or working from free-form instructions -- they follow canonical sequencing patterns:
Discovery first
Before operating on assets, the agent gathers context:
get_account_info -> get_schemas -> search_assets
This tells the agent what addons are enabled (face recognition, auto-tagging, background removal), what metadata schemas are available, and what assets match the user's request.
Single-asset inspection and delivery
get_asset_info -> get_viewable_url / get_asset_download_url / get_thumbnail
Metadata workflows
get_schemas -> update_metadata / tag_assets_bulk
External sharing
search_assets / search_collections -> create_share -> get_share_analytics / get_share_approvals
Video workflows
get_asset_info -> transcode_video / create_video_clip -> stream_video
The agent always checks asset data before video operations to verify the asset is a video and to inspect existing conversions -- avoiding redundant transcoding.
Real-world example: E-commerce product pipeline
User prompt: "Tag all new arrivals by SKU, remove backgrounds, and send a review link to the buying team."
Here's what the agent executes:
Step 1 -- Discover context:
get_account_info -> confirms BACKGROUND_REMOVAL addon is enabled
get_schemas -> retrieves schema ID and fields (sku, category, status, campaign)
Step 2 -- Find assets:
search_assets(keyword="new arrivals", include_details=true)
-> Returns 24 product images uploaded in the last 7 days
Step 3 -- Tag with metadata:
tag_assets_bulk(
asset_ids=[...24 IDs...],
schema_id="42",
data={"category": "new-arrival", "status": "pending-review", "campaign": "Spring 2026"}
)
Step 4 -- Create review share:
create_share(
file_ids=[...24 IDs...],
title="Spring 2026 New Arrivals -- Review",
allow_approval=true,
allow_feedback=true,
access_control={"expiry": "2026-03-13T00:00:00Z"}
)
-> Returns share URL
Agent response to user: "Done. 24 new arrival images tagged with Spring 2026 campaign metadata. Review page with approval workflow that includes Social media versions: https://app.filespin.io/shared/sh_abc123 -- the buying team can approve or reject each image directly."
Real-world example: Event photo distribution
User prompt: "Find all photos of the keynote speaker, tag by session, and build a branded share page for the press team."
Step 1 -- Face search:
search_by_face(asset_id="speaker_headshot_id", strictness=9.9)
-> Returns 87 photos matching the speaker's face across all event sessions
Step 2 -- Tag by session:
get_schemas -> retrieves event schema (speaker, session, event_name)
tag_assets_bulk(
asset_ids=[...87 IDs...],
schema_id="event_schema",
data={"speaker": "Jane Smith", "session": "Opening Keynote", "event": "TechConf 2026"}
)
Step 3 -- Branded press share:
create_share(
file_ids=[...87 IDs...],
title="TechConf 2026 -- Jane Smith Keynote Photos",
branding={"logo_source": "watermark", "primary_color": "#1a73e8"},
allow_feedback=true,
access_control={"expiry": "2026-03-20T00:00:00Z"}
)
-> Returns share URL
Agent response: "Found 87 photos of Jane Smith across all event sessions via face recognition. Tagged with speaker, session, and event metadata. Press share page with Social media crops: https://dashboard.filespin.io/shared/sh_press456
Addon availability and runtime checks
Some tools depend on addons being enabled on your FileSpin account. The agent always verifies addon availability before attempting addon-dependent operations:
get_account_info -> check addons_info
| Addon | Required for | Tool gated |
|---|---|---|
FACE_RECOGNITION | Face search across assets | search_by_face |
IMAGE_ANALYSIS | AI auto-tagging on upload | get_auto_tags |
BACKGROUND_REMOVAL | AI background removal | Background removal processing |
ON_DEMAND_IMAGE | Real-time image transformations | get_thumbnail, get_social_media_images |
If an addon isn't enabled, the agent will report this to the user rather than failing silently.
Best practices
-
Create a dedicated agent user. Set up a FileSpin user account specifically for AI agent access. Assign the appropriate role for the agent's intended workflows. This gives you a clean audit trail and precise permission control.
-
Use prompt templates for common workflows. Prompts encode best practices -- correct tool ordering, required checks, and sensible defaults. They're faster and more reliable than free-form instructions for repeatable operations.
-
Check addon availability first. Have the agent call ask which addons are available before attempting face recognition, auto-tagging, or background removal to verify the addon is enabled.
-
Use collections for internal grouping, shares for external distribution. Collections are for your team's organization. Shares create branded, trackable pages for external stakeholders -- with download controls, approval workflows, and analytics.
-
Let the agent handle orchestration. Don't try to script every tool call. Describe the outcome you want and let the agent decide which tools to chain and in what order. This is what MCP is designed for.