FileSpin
Search, upload, edit, transform and share images, videos and documents in FileSpin DAM.
เซิร์ฟเวอร์ MCP แบบโฮสต์
npx add-mcp 'https://mcp.filespin.io/mcp'ติดตั้งลง Claude Code, Codex, Cursor และอื่นๆ
เอกสาร
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 a focused set of tools and prompt templates covering asset search, metadata management, image transformation, video processing, sharing, and more.
Any MCP-compatible AI client -- Claude, ChatGPT, Codex, Cursor, VS Code Copilot, Windsurf, or others -- can connect to the FileSpin MCP server. The agent authenticates via OAuth2 and acts as the FileSpin user who signs in, limited to a fixed set of permissions: it can never delete assets, manage users or change account settings, whatever that user's role.
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).
Building with the FileSpin API? Install the plugin
If you write code against FileSpin with a coding agent (Claude Code, Codex or Cursor), install the FileSpin plugin instead of adding the server by hand. It connects this MCP server and adds two skills: filespin-developer, which makes the agent look up exact endpoints, parameters and image URL syntax in these docs instead of guessing, and cite the page it used; and filespin, for working with your media library: finding assets, saving files and the things your agent made with names, metadata and a collection, preparing sizes and video renditions, and creating review and share links. It also uploads files and folders from your computer when you ask ("upload ~/Desktop/shoot to FileSpin"), skipping hidden files, keys and credentials. For a walk-through, see Building with FileSpin from Claude Code, Codex and Cursor.
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.
- Add the marketplace:
/plugin marketplace add FileSpin-io/filespin-agent-plugin - Install the plugin:
/plugin install filespin@filespin - Run
/mcp, choosefilespin, 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 below. The plugin repository is also a standard Agent Plugin that Cursor can load.
Source and details: FileSpin-io/filespin-agent-plugin on GitHub.
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.
Add the FileSpin skill (optional). It helps Claude find, save, organise and share your assets the way FileSpin works, for example "find our product images and create a review link". Skills need code execution, which you can turn on in Settings > Capabilities. Download filespin.zip, go to Customize > Skills, choose + Add > Upload skill and pick the zip without unzipping it.
Claude Code
Run the following command in your terminal:
claude mcp add --transport http filespin https://mcp.filespin.io/mcp
Then start Claude Code and run /mcp to sign in to FileSpin. Developers can install the FileSpin plugin instead, which adds this server and the filespin-developer and filespin skills.
Codex
Run the following commands in your terminal:
codex mcp add filespin --url https://mcp.filespin.io/mcp
codex mcp login filespin
The second command opens a browser window to sign in to FileSpin.
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
Add to Cursor: opens Cursor and adds the FileSpin server. Cursor asks you to sign in to FileSpin on first use.
Or open your Cursor MCP configuration (Settings > MCP) and add:
{
"mcpServers": {
"filespin": {
"url": "https://mcp.filespin.io/mcp"
}
}
}
Visual Studio Code (GitHub Copilot)
Run the following command in your terminal to add the server to your VS Code user profile:
code --add-mcp '{"name":"filespin","type":"http","url":"https://mcp.filespin.io/mcp"}'
Or add it to a workspace .vscode/mcp.json (or your user-profile mcp.json):
{
"servers": {
"filespin": {
"type": "http",
"url": "https://mcp.filespin.io/mcp"
}
}
}
VS Code asks you to sign in to FileSpin when the server first starts.
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, the user signs in to FileSpin and approves the permissions the agent asks for. The agent then receives a token limited to those permissions.
Two limits apply to every request the agent makes:
- The permissions granted when connecting. A connected agent can only ever be granted these, and the user can untick any of them on the approval screen:
Permission What it allows read_assetsView and download assets and their conversions write_assetsUpload and edit assets, update metadata, create and manage shares manage_collectionsCreate and edit collections manage_schedulesCreate and manage the user's scheduled AI agent runs send_notificationsSend email notifications on the user's behalf read_statsView usage statistics and analytics (read-only) - The user's FileSpin role. Within those permissions, the agent can only do what the signed-in user's role allows:
Role What a connected agent can do Admin Everything in the permissions above: upload, edit and tag assets, share, manage collections, schedule agent runs, send notifications, view usage stats Manager Upload, tag, share, manage collections, view analytics Creator Upload and manage own assets, create shares User View and search assets, download
No role, Admin included, gives a connected agent:
- Deleting or purging assets. Delete is deliberately not a grantable permission.
- Managing users or teams. Inviting, removing or changing the role of users stays in the dashboard.
- Changing account settings. Settings, AI budgets, API keys and billing can only be changed in the dashboard or with an API key.
Key points:
- No separate API key is needed. The agent signs in as a FileSpin user through OAuth 2.0.
- Every action is attributed. The agent's actions run under the signed-in user's account and are listed on the dashboard's Agent activity page.
- You can disconnect an agent at any time. Each connection appears under Connected apps in your profile, where you can sign it out immediately; admins can review and sign out any user's connections.
[!-success] -success tip
For a shared or unattended agent, create a dedicated FileSpin user with the least privileged role that covers its workflows. Its actions are then easy to tell apart from anyone else's.
Available tools
The MCP server groups its tools into seven capability areas. Agents compose these into end-to-end workflows.
| Category | What it covers |
|---|---|
| Asset management | Search and inspect assets, upload or replace files, update metadata (single or bulk), discover metadata schemas, and check account capabilities and enabled addons. Agents that can run shell commands (Claude Code, Codex, Cursor) can also upload files and folders from your computer: each file goes straight to your FileSpin storage and keeps its folder path, so you can find it by folder name. Chat apps without a shell (Claude, ChatGPT) can open a FileSpin upload page instead: you sign in, pick the files or a folder and press Done, and the agent gets the uploaded assets. |
| Image transformation | Generate on-brand image variants -- resizing/cropping, social-platform formats, and logo or text watermarks. A single branded-image tool covers both social-crop output and (via preserve_original_size: true) watermark-only output over the original dimensions. Background removal is also available. |
| AI and addons | Face search across the library and retrieval of AI-generated auto-tags with confidence scores. Addon-gated -- available when the corresponding addon is enabled on the account. |
| Sharing and distribution | Create, list, search, update, and delete branded share pages; check approval workflow status; review analytics; and reuse share templates. |
| Collections | Create and search collections, manage their member assets, and generate ZIP download links. |
| Video | Transcode videos to specified resolutions and formats, create trimmed/custom clips, and retrieve HLS streaming URLs. |
| Delivery | Generate CDN view URLs and signed download URLs for assets. |
| Developer docs | Search these developer docs and guides, find an API operation and get its exact parameters, request body and responses, and read any docs page as markdown. For coding agents writing code against the FileSpin API. |
For the authoritative, always-current tool list, have your agent call the standard MCP tools/list endpoint after connecting.
Prompt templates
The MCP server also registers 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
[!-info] -info What permissions does the agent have?
The agent gets the permissions the user approved when connecting (view and download, upload and edit, collections, scheduled agent runs, notifications and read-only usage stats), narrowed further by the user's FileSpin role. An Admin-connected agent does not get admin access: deleting assets, managing users and changing account settings are never available to a connected agent. See Authentication and permissions.
[!-info] -info Can I restrict what the agent can do?
Yes, in two ways. Untick any permission you don't want the agent to have on the approval screen when it connects. And for a shared or unattended agent, create a dedicated FileSpin user account 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.
[!-info] -info How do I audit agent actions?
Every tool call the agent makes runs under the signed-in user's account and is listed on the dashboard's Agent activity page, by agent, with what succeeded, what failed and what was refused. Prompts and message content are not stored.
[!-info] -info 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.
[!-info] -info 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.
[!-info] -info Can the agent delete or purge assets?
No. Deleting assets is not a permission a connected agent can be granted, whatever the user's role, so an agent can neither delete nor purge assets. This prevents data loss through agent operations. Assets can still be deleted in the dashboard or through the API with an API key.
[!-info] -info 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.
[!-info] -info What happens if an addon is not enabled on my account?
Some capabilities depend on specific addons being enabled -- face search requires the Face Recognition addon, auto-tag retrieval requires Image Analysis, and background removal requires the Remove Background addon. If the addon is not enabled, the agent will report this to the user rather than failing silently. The agent can query account information through the MCP server to check which addons are available on your account.