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 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 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).
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 the filespin-developer skill, 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.
Claude Code (inside Claude Code):
/plugin marketplace add FileSpin-io/filespin-agent-plugin
/plugin install filespin@filespin
Then run /mcp, choose filespin, and sign in to 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.
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 skill.
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 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 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. |
| 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
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 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.