MCP Server
FileSpin provides a hosted MCP (Model Context Protocol) server that lets AI agents connect to your FileSpin account and perform asset management operations through natural language. The server exposes 33 tools and 36 prompt templates covering asset search, metadata management, image transformation, video processing, sharing, and more.
Any MCP-compatible AI client -- Claude, ChatGPT, Cursor, VS Code Copilot, Windsurf, or others -- can connect to the FileSpin MCP server. The agent authenticates via OAuth2 and inherits the permissions of the authenticating FileSpin user.
For workflow patterns, real-world examples, and prompt template details, see the AI Agent Integration guide.
MCP server URL
https://mcp.filespin.io/mcp
Authentication: OAuth 2.0 (the agent will open a browser window for the user to log in to FileSpin).
Setup by client
Claude
- Open Settings in your Claude workspace.
- Go to Connectors (or Integrations or similar for MCP integrations).
- Add a new MCP connector with the URL:
https://mcp.filespin.io/mcp - Save. Claude will prompt for FileSpin login on first use.
Claude Code
Run the following command in your terminal:
claude mcp add filespin --transport streamable-http https://mcp.filespin.io/mcp
ChatGPT
- Open Settings in ChatGPT.
- Navigate to Connectors or MCP Integrations.
- Add a new connector with the URL:
https://mcp.filespin.io/mcp - Save. ChatGPT will prompt for FileSpin login on first use.
Cursor
Open your Cursor MCP configuration (Settings > MCP) and add:
{
"mcpServers": {
"filespin": {
"url": "https://mcp.filespin.io/mcp"
}
}
}
Visual Studio Code (GitHub Copilot)
Add to your VS Code settings.json:
{
"mcp": {
"servers": {
"filespin": {
"url": "https://mcp.filespin.io/mcp"
}
}
}
}
Windsurf
Add to your Windsurf MCP configuration:
{
"mcpServers": {
"filespin": {
"url": "https://mcp.filespin.io/mcp"
}
}
}
Other MCP clients
Any client that supports the MCP standard can connect using the server URL:
https://mcp.filespin.io/mcp
The server uses OAuth 2.0 authentication. Your client must support streamable HTTP transport and OAuth 2.0 authorization flows.
Authentication and permissions
The FileSpin MCP server uses standard OAuth 2.0. When an agent connects for the first time, a browser window opens and the user logs in to FileSpin. The agent receives a token scoped to that user's account role.
What the agent can do depends entirely on the FileSpin account role of the authenticated user:
| Role | Capabilities |
|---|---|
| Admin | Full access -- upload, tag, share, manage users, configure settings |
| Manager | Upload, tag, share, manage collections, view analytics |
| Creator | Upload and manage own assets, create shares |
| User | View and search assets, download |
Key points:
- No separate API key is needed -- the agent inherits the user's existing permissions.
- Audit trail -- every action the agent takes is logged under the authenticated user's account.
- Role-based control -- restrict agent capabilities by assigning appropriate FileSpin roles.
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.
Complete purging of assets is not available via MCP.
Available tools
The MCP server exposes 33 tools across seven categories. These are atomic operations that agents compose into workflows.
Asset management
| Tool | Description |
|---|---|
search_assets | Search assets by keyword, filters, and metadata |
get_asset_info | Retrieve full metadata and conversion details for an asset |
upload_asset | Upload a new file to FileSpin |
replace_asset | Replace an existing asset's file while preserving its ID and metadata |
update_metadata | Update custom metadata fields on a single asset |
tag_assets_bulk | Apply metadata tags to multiple assets at once |
get_schemas | List available custom metadata schemas and their fields |
get_account_info | Retrieve account capabilities, enabled addons, and plan details |
Image transformation
| Tool | Description |
|---|---|
get_thumbnail | Generate a resized or cropped image variant |
get_social_media_images | Generate platform-specific image sizes (Instagram, Facebook, LinkedIn, etc.) |
watermark_image_assets_with_image_overlay | Apply a logo or image watermark to assets |
watermark_image_assets_with_text_overlay | Apply a text watermark to assets |
remove_background | Remove the background from an image using AI |
AI and addons
| Tool | Description |
|---|---|
search_by_face | Find assets containing a specific person using face recognition |
get_auto_tags | Retrieve AI-generated labels and confidence scores for an asset |
Sharing and distribution
| Tool | Description |
|---|---|
create_share | Create a branded share page with optional approval workflow |
list_shares | List all active share pages |
search_shares | Search share pages by keyword or filter |
get_share_info | Retrieve details of a specific share page |
update_share | Modify an existing share page |
delete_share | Remove a share page |
get_share_analytics | Retrieve view and download analytics for a share |
get_share_approvals | Check approval status on a share with approval workflow |
list_share_templates | List available share page templates |
Collections
| Tool | Description |
|---|---|
create_collection | Create a new asset collection |
search_collections | Search collections by name or metadata |
get_collection | Retrieve collection details and member assets |
update_collection | Update collection name, description, or settings |
update_collection_assets | Add or remove assets from a collection |
get_collection_download_url | Generate a ZIP download link for all assets in a collection |
Video
| Tool | Description |
|---|---|
transcode_video | Transcode a video to specified resolutions and formats |
create_video_clip | Create a trimmed clip from a video with start/end times |
stream_video | Retrieve HLS streaming URL for a video asset |
Delivery
| Tool | Description |
|---|---|
get_viewable_url | Generate a CDN URL for viewing an asset |
get_asset_download_url | Generate a signed download URL for an asset |
Prompt templates
The MCP server also registers 36 prompt templates across 11 workflow categories. Prompt templates are multi-step recipes that guide the agent through complex operations -- the agent discovers them automatically and executes the right tool calls in sequence.
| Category | Prompts | Summary |
|---|---|---|
| E-commerce | 2 | Product image tagging, social output, review sharing |
| Events | 2 | Speaker/sponsor discovery, session tagging, press shares |
| Attractions | 2 | Guest face discovery, preview watermarking, gallery sharing |
| Social Media | 3 | Platform-specific sizing, logo and text watermarks |
| AI Workflows | 4 | Face search, addon discovery, auto-tag retrieval |
| Video Processing | 2 | Transcode with dedup check, custom clip creation |
| Creative | 2 | Face-centered profiles, responsive hero images |
| Branded Shares | 8 | Press kits, galleries, review pages, template shares, analytics |
| Collections | 3 | Save search to collection, ZIP download, membership management |
| Administration | 4 | Bulk tagging, metadata audit, review discovery, standardization |
| Content Creation | 4 | Save HTML, CSV, Markdown, and metadata exports to FileSpin |
For detailed descriptions of each prompt template and real-world workflow examples, see the AI Agent Integration guide.
FAQ
What permissions does the agent have?
The agent inherits the exact permissions of the FileSpin user who authenticated the OAuth2 connection. If the user is an Admin, the agent has admin-level access. If the user has a Creator role, the agent can only perform creator-level operations. There is no separate permission model for MCP -- it uses the same role-based access control as the rest of FileSpin.
Can I restrict what the agent can do?
Yes. Create a dedicated FileSpin user account for the agent and assign it the most restrictive role that still covers the intended workflows. For example, if the agent only needs to search and view assets, assign the User role. If it needs to upload and tag, assign Creator or Manager.
How do I audit agent actions?
Every tool call the agent makes is executed under the authenticated user's account and logged in FileSpin's standard audit trail. You can review agent activity the same way you review any user's activity -- through the Dashboard activity logs or the Usage Stats API.
Which AI clients are supported?
Any client that implements the Model Context Protocol (MCP) standard with streamable HTTP transport and OAuth 2.0 support. This includes Claude (Desktop, Code, Team, Enterprise), ChatGPT, Cursor, VS Code with GitHub Copilot, Windsurf, Zed, and others. If your client supports adding an MCP server URL, it will work with FileSpin.
Is an API key required?
No. The FileSpin MCP server uses OAuth 2.0 authentication exclusively. The agent authenticates through a browser-based login flow, and no API key needs to be configured in the client.
Can the agent delete or purge assets?
The agent can soft-delete assets if the authenticated user's role permits deletion. However, complete purging of assets is not available via MCP. This is a safety measure to prevent irreversible data loss through agent operations.
Do I need to install anything locally?
No. The FileSpin MCP server is fully hosted -- there is nothing to install, no Docker containers to run, and no local processes to manage. You only need to add the server URL to your AI client's configuration.
What happens if an addon is not enabled on my account?
Some tools depend on specific addons (e.g., search_by_face requires the Face Recognition addon, get_auto_tags requires Image Analysis). If the addon is not enabled, the agent will report this to the user rather than failing silently. Use get_account_info to check which addons are available on your account.