Skip to main content

Model Context Protocol (MCP) Server

The Files.com Model Context Protocol (MCP) Server lets your AI application interact with your Files.com site. The AI agent works against your site as if it were an extension of your team. Files.com applies the permissions of the account or API key you authorize and records the AI's actions in the standard audit logs.

Your AI can use the MCP Server to upload and download files, query folders, manage users, and run other site operations.

The Remote MCP Server is hosted by Files.com and is the best choice for most customers. Use it to connect over a network. The Local MCP Server is a Python package for local use only, on the same machine as your AI client.

Model Context Protocol

Model Context ProtocolExternal LinkThis link leads to an external website and will open in a new tab (MCP) standardizes communication between an AI application and services that provide tools and context. Your AI application is the host. A client component inside it communicates with each connected server, such as the Files.com MCP Server. The host manages the model conversation and decides what information and tool access to make available.

The protocol distinguishes tools, operations an application can call; resources, data an application can read as context; and prompts, reusable message templates offered by a server. Each server advertises which of these capabilities it supports.

For Files.com work, the model can request an available tool, the host sends that request through its MCP client, and the Files.com server performs the operation within the authorized permissions. The result returns to the host for the model to use. The host can repeat this tool loop or present an answer. MCP supplies the connection; your application controls model behavior, conversation context, and whether it asks for approval before tool calls.

Remote vs. Local MCP Server

The Remote MCP Server is the recommended choice for working with files, folders, users, and other data on your Files.com site. Files.com operates and updates the server, so you do not maintain a local Python package. It also works with web and mobile AI clients that cannot launch a local process. Choose Sign In with Files.com to connect with your account, or API Key authentication when you need a fixed credential or the key's access restrictions.

Choose the Local MCP Server when your AI client supports only local servers over standard input and output (STDIO), or when you need to upload files from your computer and save downloads there. Your AI client launches the Python package on the same machine. You maintain that package and supply an API key. Local still requires network access to the Files.com API; it does not work offline.

Both versions provide tools for site operations. The local upload and download tools are available only on the Local MCP Server. Connecting to Remote does not give that server access to files on your computer.

If you already use Local for site operations and do not need its local file transfers, switching to Remote removes the need to maintain the Python package. Using Sign In with Files.com also removes the need to keep an API key in that connection's configuration. Keep Local when its local transfer tools or your client's STDIO requirement matter to your work. An API key can be used with either server, so needing one does not by itself require Local.

Switching changes how your AI client connects to the same Files.com site. When changing authentication methods, review MCP Access Permissions: browser sign-in uses the signed-in user's permissions and does not inherit restrictions applied to an API key. The Claude Desktop switching instructions cover changing the connection and retiring its old credential.

Regional-only Global Acceleration does not confine the Remote MCP Server's requests to your site's storage region. A Site Administrator can disable all AI features, which also blocks the Remote MCP Server, if those requests do not meet your geographic requirements.

Authentication

Before authorizing a client, review MCP to choose appropriate permissions and understand how to end its access.

Remote MCP tool calls are exempt from the additional password or 2FA confirmation used for selected account and credential changes. Review MCP re-authentication when choosing the account or key to authorize.

Sign In with Files.com

The Remote MCP Server supports browser-based sign-in using OAuth 2.0. Your AI client discovers the sign-in flow automatically through standard OAuth metadata endpoints and opens a browser to authenticate against your Files.com site. On first connection, you log in and grant access. The client receives a bearer token representing your Files.com session. No API key is required.

If your Files.com site uses single sign-on (SSO), the sign-in flow redirects to your identity provider as normal. SSO authentication works transparently with the OAuth flow.

Sign In with Files.com is available on the Remote MCP Server only. The Local MCP Server uses API Key authentication.

Dynamic Client Registration(DCR) and Client ID Metadata Documents (CIMD)

Files.com supports two OAuth client registration methods for the Remote MCP Server: CIMD (Client ID Metadata Documents) and DCR (Dynamic Client Registration).

CIMD lets a client use an HTTPS metadata URL as its identity. Files.com reads the client details from that address, giving the application a consistent identity and a domain you can inspect during sign-in. Clients that support CIMD connect without enabling DCR or manually registering the application.

DCR lets a client submit its name and redirect addresses to obtain a client ID at connection time. The client supplies those details itself; registration does not verify that it is published by the company named in its display name.

DCR is disabled by default. Leaving it disabled when your clients support CIMD keeps sign-in tied to the metadata URL approach without enabling an additional registration method. The MCP authorization specificationExternal LinkThis link leads to an external website and will open in a new tab retains DCR for compatibility with earlier clients.

After registration, you sign in and approve access. The client then operates with the permissions of the account you authenticated. Before approving it, check that you initiated the connection and recognize the client and redirect address.

Site Administrators can enable DCR using the MCP Dynamic Client Registration setting. Check your client's documentation and enable it only if the client requires DCR. If a client connects successfully without DCR enabled, leave the setting off.

When DCR is disabled and a client that does not support CIMD attempts to connect, the sign-in fails with the Couldn't Complete OAuth Redirect error.

Interstitial OAuth Warning Page

Before granting access, the sign-in flow displays a warning page. Confirm that the requesting client and redirect address match the connection you intended to configure.

For CIMD, the page displays the client's metadata domain alongside its redirect destination. A recognizable domain helps you identify the client, but does not replace checking that you initiated the request.

API Key

Both the Remote and Local MCP Servers accept a Files.com API Key for authentication. Pass the key as the value of the X-FilesAPI-Key HTTP header (Remote MCP Server) or the FILES_COM_API_KEY environment variable (Local MCP Server).

For details on what actions each authentication method permits, see MCP Access Permissions.

Getting Started with the Remote MCP Server

The Remote MCP Server is the fastest way to connect your AI client to Files.com. Files.com hosts and operates the server, so there is nothing to install or maintain. You can connect to multiple Files.com sites at once by adding an entry for each site in your configuration.

To connect, configure your AI client to use the Files.com MCP endpoint at https://<mysite>.files.com/api/ai/mcp/v1/ or https://<mycustomdomain>/api/ai/mcp/v1/.

The Remote MCP Server supports two authentication methods. Most clients can use Sign In with Files.com: your AI client discovers the sign-in flow automatically and opens a browser to authenticate with your Files.com account. No API key setup is required.

Clients that cannot open a browser, or that need a fixed credential for automated workflows, can authenticate with a Files.com API Key passed as the X-FilesAPI-Key HTTP header.

Sign In with Files.com works with any MCP-compliant client that supports OAuth, including Claude Code, Claude for mobile, and web-based AI assistants. This is the easiest method for most users and the only method that works with mobile clients such as the Claude app for iOS and Android.

For Claude for web and Claude for mobile, use the application's settings to add the Files.com MCP endpoint as a custom connector. Claude will open a browser to complete sign-in the first time you connect. For step-by-step Claude Desktop instructions, see the Quickstart for Claude Desktop. For other AI clients, refer to your client's documentation for configuring a remote MCP server.

Getting Started with the Local MCP Server

The Local MCP Server communicates with your AI client on the same machine through standard input and output (STDIO). The local process connects to the Files.com API to perform site operations. It does not support SSE or accept network connections from AI clients. Use the Remote MCP Server for those connections.

Install the Local MCP Server from our GitHub repositoryExternal LinkThis link leads to an external website and will open in a new tab or by using the pip Python package managerExternal LinkThis link leads to an external website and will open in a new tab. It is also listed on the Official MCP RegistryExternal LinkThis link leads to an external website and will open in a new tab, GlamaExternal LinkThis link leads to an external website and will open in a new tab, PulseMCPExternal LinkThis link leads to an external website and will open in a new tab, MCP.soExternal LinkThis link leads to an external website and will open in a new tab, and MCP MarketExternal LinkThis link leads to an external website and will open in a new tab. The Local MCP ReferenceExternal LinkThis link leads to an external website and will open in a new tab provides package installation, client configuration, and tool names for the Python server. Then configure your AI client to use it.

Refer to the documentation for your AI application to configure it to use the Files.com MCP Server.

For customers using Claude Desktop, we provide some quickstart instructions to help you get up and running quickly.

Local Directory Restriction

The Local MCP Server can upload files from your computer and save downloads there. If the AI's work belongs in one local folder, set FILES_COM_LOCAL_ROOT to limit the local paths used for the client's upload and download requests to that folder and its subfolders.

Set FILES_COM_LOCAL_ROOT in the environment your MCP client passes to the server, alongside FILES_COM_API_KEY. Its value must be an absolute path to an existing local directory. Restart the client after changing the setting so it launches the server with the new value. The Claude Desktop configuration example includes this option.

The server resolves .. and symbolic links before checking each requested local path against the configured directory. A download can create a new file, but its destination directory must already exist. Relative transfer paths start from the server's working directory, not from FILES_COM_LOCAL_ROOT; use absolute transfer paths to make the intended location clear.

FILES_COM_LOCAL_ROOT does not separate operating-system accounts. Use operating-system permissions so that only the account running the server has write access to the configured directory and its subdirectories. Another account with write access inside the root can redirect transfers outside it through symbolic links it places there.

The setting is optional. An omitted or empty value allows transfers to use any local path the server's operating-system account can access. An invalid nonempty value prevents the server from starting. This local restriction is separate from API key permissions, which control access to your Files.com site. The Security Reference explains how the local and site controls work together.

Available MCP Tools

Within an MCP server, a "toolExternal LinkThis link leads to an external website and will open in a new tab" represents a capability or function that the AI can interact with.

Our MCP server has a limited set of available MCP tools today. More tools will be added over time.

Updating the Local MCP Server

The local MCP Server can be updated to the latest version via the pip Python package managerExternal LinkThis link leads to an external website and will open in a new tab by using the command:

pip install --upgrade files-com-mcp

For a package installed into a uv virtual environment, use uv pip install --upgrade files-com-mcp. When the client launches the server with uvx, run uvx --upgrade files-com-mcp to refresh its cached package, then restart the client.

Removing the Local MCP Server

To stop an AI client from launching the Local MCP Server, remove its Files.com local server entry from that client's configuration and restart the client. You can connect to Remote while the local package remains installed; uninstalling it is optional.

For the uvx setup in the Claude Desktop quickstart, removing the entry is enough to stop launching the server. There is no separately installed package to uninstall.

Uninstalling a package installed with pip or uv pip affects any other client using that installation. Removing a connection or uninstalling the package leaves your Files.com files and previously downloaded files in place. Neither action revokes the API key. Revoke a key dedicated to the retired connection once you have verified its replacement. If another integration uses the same key, replace that integration's credential before revoking it.

For a package installed with pipExternal LinkThis link leads to an external website and will open in a new tab, use:

pip uninstall files-com-mcp

When using the uv environment manager, use the command:

uv pip uninstall files-com-mcp