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, 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 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. |
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.