Files.fm API
Markdown sourceOpenAPI JSONSwagger UIInteractive documentation

Files.fm Hosted MCP Connector

Files.fm exposes a hosted Model Context Protocol (MCP) endpoint for AI clients that need access to Files.fm files and API documentation. Storage writing tools are available only on deployments that explicitly enable them.

Endpoint:

https://api.files.fm/api/mcp

Transport:

Supported initialization-based revisions: 2025-03-26, 2025-06-18, and 2025-11-25. The default initialization response remains 2025-06-18. The server also supports 2026-07-28 with per-request metadata and server/discover; do not send an initialize handshake using the modern revision. Unknown protocol headers return 400 with supported-version information.

The existing 2024-11-05 JSON messages remain accepted over this server's custom POST compatibility transport. This does not provide that revision's deprecated standard SSE transport; clients requiring SSE cannot connect through it.

For modern HTTP requests include MCP-Protocol-Version, Mcp-Method, and, for tool/resource calls, Mcp-Name. The matching protocol version and client capabilities go in params._meta. Modern results include resultType: "complete"; the old response shape remains available to initialization-based clients.

Authentication

Private file tools require an API access token:

Authorization: Bearer <user_id>:<api_token>

Use a Files.fm user access token with type API or ALL. Tokens are managed in the Files.fm account API key UI.

Do not put credentials in query strings. The MCP endpoint rejects query-string parameters.

Public filesfm_search_docs, filesfm_get_doc, documentation resource reads, and discovery/list methods do not require a token. Private file access can additionally use the isolated OAuth profile when operators have enabled it on that deployment. OAuth tokens are short-lived and distinct from general API keys. Reading requires files:read; storage writes require files:read files:write and explicit consent. Existing read-only grants are not upgraded automatically, and refresh cannot add scopes. If OAuth discovery reports unavailable, use public documentation or a supported client's configured API-key header.

Capabilities

Supported JSON-RPC methods:

With FILESFM_MCP_WRITES_ENABLED=1, the connector creates folders, adds new files, renames, and moves files/folders within one owner's account. Deployments with writes disabled expose reading/search tools only. It does not delete, replace existing file content, transfer ownership, restore, or change sharing settings. API/ALL keys can use enabled writes within account permissions; OAuth connections additionally need files:write.

It also does not enumerate structured DVS tasks/projects or perform DVS writes. Use public documentation to prepare the separate DVS JSON API requests with its own credentials and schema discovery.

Tools

filesfm_get_root_folder

Returns the authenticated user's root folder metadata.

filesfm_list_folder

Lists visible files and direct child folders in a folder.

Arguments:

{
  "folder_hash": "abc123",
  "limit": 100,
  "offset": 0
}

filesfm_get_folder_info

Returns metadata for one visible folder.

Arguments:

{
  "folder_hash": "abc123"
}

filesfm_get_file_info

Returns metadata for one visible file.

Arguments:

{
  "file_hash": "abc123"
}

filesfm_read_file

Reads one visible file when the token has download rights.

Arguments:

{
  "file_hash": "abc123",
  "max_bytes": 26214400
}

Text files are returned inline as UTF-8 text. Binary files below the inline limit are returned as MCP blob content with base64 data. Larger files return metadata plus a Files.fm URL instead of loading the full file into memory.

Default and maximum inline size: 25 MB.

filesfm_search_files

Searches visible files and folders for the authenticated user through the same central Files.fm search used by the web UI. Simple search can match names plus indexed/searchable metadata such as descriptions, tags, image text/object labels, and common file metadata fields when available.

Arguments:

{
  "query": "invoice",
  "limit": 20
}

filesfm_search_docs

Searches local Files.fm API and MCP Markdown documentation. This tool is public and does not require bearer authentication.

Arguments:

{
  "query": "upload file",
  "limit": 8
}

Search results contain a public url, a filesfm-docs:// URI, title and snippet. Read the complete document before implementing a request. Small Latvian/English keyword aliases help tasks/project discovery; this is keyword search, not semantic retrieval.

filesfm_get_doc

Reads the complete published Markdown document or OpenAPI specification without authentication. This is useful in clients that expose tools but not MCP resources.

{"uri":"filesfm-docs://filesfm_api_dvs_tasks.md"}

The JSON result contains uri, canonical url, and complete text. Existing JSON tool results remain in text content and also provide structuredContent; declared output schemas apply to that structured object. File reads use text/embedded resources and do not declare a single JSON output schema.

Resources

Static documentation resources:

The document catalog drives discovery, navigation, and this allow-list. Unpublished paths and arbitrary filesystem paths are rejected.

Private resource templates:

Private resources require bearer authentication and use the same access checks as the tools.

Limits

Request bodies are capped at 1 MB. Inline file reads are capped at 25 MB.

The MCP endpoint applies fixed-window rate limits by client IP, authenticated user, and bearer token for private tools. Expensive operations such as filesfm_search_files and filesfm_read_file have stricter limits than metadata and folder listing calls. Public documentation search and documentation resource reads are IP-limited.

When a limit is exceeded, the endpoint returns HTTP 429 with a JSON-RPC error message that includes the retry time in seconds.

Current fixed-window limits per action: public document search/read 120 requests/minute and 2,400/hour per IP; private search 30/minute and 600/hour per token; private file read 40/minute and 700/hour per token; folder listing 90/minute and 1,800/hour per token. Additional user/IP buckets apply. Limits are operational settings, not a contractual capacity guarantee. Folder listing may return a short page after access-right filtering; its offset addresses the raw folder/file sequence, not just the visible result count.

Example JSON-RPC Calls

Initialize:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

Search docs:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "filesfm_search_docs",
    "arguments": {
      "query": "API authentication"
    }
  }
}

Read a file:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "filesfm_read_file",
    "arguments": {
      "file_hash": "abc123"
    }
  }
}

Client Setup

Client setup and successful HTTP requests are different from a completed integration. The official configuration syntax below is checked against client documentation; operator/customer smoke tests must record the actual product/version and public/private tool result.

ChatGPT

Add the remote MCP URL https://api.files.fm/api/mcp through the custom MCP/plugin setup available to your account. For public documentation, choose no authentication and test filesfm_search_docs followed by filesfm_get_doc. Account/workspace policies determine whether custom connectors are available.

Private file access requires a supported credential setup. For OAuth, the isolated server profile must first be enabled; then use its discovered OAuth settings. Do not place an API token in the server URL. Generic MCP tools do not by themselves implement ChatGPT company-knowledge/deep-research search/fetch compatibility.

Official OpenAI MCP setup

Codex

Example config.toml remote MCP server:

[mcp_servers.filesfm]
url = "https://api.files.fm/api/mcp"
bearer_token_env_var = "FILESFMMCP_BEARER_TOKEN"

Environment variable value:

export FILESFMMCP_BEARER_TOKEN="<user_id>:<api_token>"

Cursor

Example .cursor/mcp.json:

{
  "mcpServers": {
    "filesfm": {
      "url": "https://api.files.fm/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FILESFMMCP_BEARER_TOKEN}"
      }
    }
  }
}

Opencode

Example remote MCP configuration:

{
  "mcp": {
    "filesfm": {
      "type": "remote",
      "url": "https://api.files.fm/api/mcp",
      "headers": {
        "Authorization": "Bearer ${FILESFMMCP_BEARER_TOKEN}"
      }
    }
  }
}

Claude Clients

For Claude Code, use HTTP MCP with an environment-expanded header:

claude mcp add --transport http filesfm https://api.files.fm/api/mcp \
  --header "Authorization: Bearer ${FILESFMMCP_BEARER_TOKEN}"

For Claude web/Desktop remote connectors, add the same URL and choose no sign-in for public documentation. Current connector setup also supports fixed request headers for API-key services; where that setting is available, configure:

Authorization: Bearer <user_id>:<api_token>

Use the current Claude client UI or configuration syntax because remote MCP support differs by Claude product and release.

Alternatively choose OAuth after the server's OAuth profile is enabled. Verify sign-in and a private read in the actual client. A local Claude Desktop stdio configuration is a different interface from a hosted remote connector.

Claude Code MCP · Claude remote connector setup

Gemini

Gemini CLI supports remote HTTP MCP in its MCP server settings. Configure the endpoint and the documented Authorization header for private files, or omit the header for public documentation. The Gemini web application and Gemini API URL Context are separate products: a successful CLI MCP connection does not establish either web URL retrieval or native MCP support in Gemini web.

Gemini CLI MCP · Gemini URL Context

Modern discovery example

POST /api/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: server/discover

{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"example-client","version":"1.0"}}}}

For tools/call add Mcp-Name: filesfm_get_doc and put name, arguments and the same _meta object in params. The Mcp-Name value must match the body. GET returning 405 is intentional; a POST JSON response does not require SSE.

MCP transport · Version compatibility

Security and Limits

Storage Writing Tools (v1.2)

With FILESFM_MCP_WRITES_ENABLED=1, tools/list includes seven additional tools. With writes disabled, the original eight remain. Discovery is public; execution requires API/ALL authentication or an OAuth grant containing files:read files:write, plus account permissions. Existing read-only grants are not upgraded. Folder/file access.can_add and access.can_edit describe effective connection permissions.

Tool Required arguments
filesfm_create_folder parent_folder_hash, folder_name
filesfm_upload_file folder_hash, file_name, content, encoding (utf8 or base64)
filesfm_import_file folder_hash, file_name, exactly one of source_url or file
filesfm_rename_file file_hash, file_name
filesfm_rename_folder folder_hash, folder_name
filesfm_move_file file_hash, target_folder_hash
filesfm_move_folder folder_hash, target_folder_hash

Create, upload and reorganize

Discover the parent with filesfm_get_root_folder / filesfm_list_folder; never guess hashes. Then call:

{"jsonrpc":"2.0","id":10,"method":"tools/call","params":{"name":"filesfm_create_folder","arguments":{"parent_folder_hash":"ACTUAL_PARENT_HASH","folder_name":"Reports"}}}

Results contain status (created, updated, or unchanged) and item with type, hash, name, parent_folder_hash, size, mime_type, and access_type. Retain item.hash for later calls. Folders request PRIVATE access; mandatory parent settings can override it, so inspect the returned access_type.

{"jsonrpc":"2.0","id":11,"method":"tools/call","params":{"name":"filesfm_upload_file","arguments":{"folder_hash":"RETURNED_FOLDER_HASH","file_name":"report.csv","encoding":"utf8","content":"name,value\nexample,1\n"}}}

For binary files, send standard padded base64 without whitespace or a data-URL prefix. Inline content is limited to 10 MiB decoded, and the entire JSON request to 16 MiB. The wire limit applies to heavily escaped UTF-8 text too. Other tools retain the 1 MiB request limit. Client/model limits may be lower; these server limits do not guarantee a chat client can send a 10 MiB argument.

Use the returned file hash with read, rename, and move tools. Moves preserve names and stay within one owner account; they require source removal and destination addition rights. Root folders cannot move/rename; folders cannot move into themselves or descendants. Destination sharing may change effective access. Deletion, replacement, ownership transfer, sharing changes, and DVS writes are not exposed.

Existing files and attachments

A hosted server cannot open local, file://, Windows or chat sandbox paths. The client must provide bytes or an accessible HTTPS download URL:

{"jsonrpc":"2.0","id":12,"method":"tools/call","params":{"name":"filesfm_import_file","arguments":{"folder_hash":"ACTUAL_FOLDER_HASH","file_name":"attachment.pdf","source_url":"https://example.com/attachment.pdf"}}}

A supporting ChatGPT client may instead provide a file object:

{"folder_hash":"ACTUAL_FOLDER_HASH","file_name":"attachment.pdf","file":{"download_url":"https://example.com/temporary-download","file_id":"file_example","mime_type":"application/pdf","file_name":"attachment.pdf"}}

The server advertises openai/fileParams:["file"]. download_url and file_id are required; attachment mime_type / file_name are optional. The outer name is the explicit destination name. file_id is a client reference, not a Files.fm hash or credential. This extension requires verification in the actual ChatGPT connection; ordinary MCP clients can use source_url.

HTTPS imports are limited to 100 MiB, public IPv4 destinations on port 443, three supported redirects, and a 60-second download deadline. Each redirect is validated again. Relative redirects must be root-relative; otherwise provide the final URL. Private/reserved IPs, IPv6, URL credentials and fragments are rejected. MCP credentials and cookies are never forwarded. Obtain a fresh URL from the client if it has expired. Attachment MIME metadata is not trusted for storage.

Errors and retries

Writes enforce account policies, quota, applicable file limits, antivirus, locks and direct-sharing/read-only restrictions. Encrypted folders require their dedicated encryption client. Add-only destinations do not grant access to existing files.

Name conflicts return name_conflict; nothing is overwritten or automatically suffixed. Other errors include permission_denied, quota_exceeded, file_locked, ownership_transfer_denied, file_too_large, virus_detected, invalid_source, and source_unavailable. Tool errors use MCP isError:true. Missing OAuth write permission returns HTTP 403 and WWW-Authenticate: Bearer error="insufficient_scope", scope="files:read files:write".

After a timeout/uncertain write, inspect the destination before retrying. Create/upload/import have no general idempotency-key guarantee. Repeated rename/move to the object's current name/parent returns unchanged. A core storage failure may require reconciliation even if the tool reports an error.

All writes share 30/minute and 300/hour per user. Imports also have 6/minute and 60/hour limits. Additional IP buckets apply. These operational limits do not expand storage entitlements.