Files.fm Hosted MCP Connector

Files.fm exposes a hosted Model Context Protocol (MCP) endpoint for AI clients that need read-only access to Files.fm files and Files.fm API documentation.

Endpoint:

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

Transport:

Streamable HTTP request/response over POST
JSON-RPC 2.0 body
Content-Type: application/json
GET and SSE are not enabled in v1

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, scoped to read-only files, and distinct from general API keys. If OAuth discovery reports unavailable, use public documentation or a supported client's configured API-key header; do not assume an OAuth login is available.

Capabilities

Supported JSON-RPC methods:

initialize
tools/list
tools/call
resources/list
resources/read
resources/templates/list
ping (initialization-based clients)
server/discover (modern clients)

The connector is read-only. It does not upload, rename, move, delete, restore, share, or change files.

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:

filesfm-docs://README.md
filesfm-docs://filesfm_api_v2.md
filesfm-docs://filesfm_api_dms.md
filesfm-docs://filesfm_mcp.md
filesfm-docs://filesfm_api_dav.md
filesfm-docs://filesfm_api_protocols.md
filesfm-docs://filesfm_api_dvs_tasks.md
filesfm-docs://filesfm_api_storage.md
filesfm-docs://openapi.yaml
filesfm-docs://openapi.json

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

Private resource templates:

filesfm://folder/{folder_hash}
filesfm://file/{file_hash}

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

HTTPS is required for production use.
Bearer auth is accepted only from the Authorization header.
Query-string credentials are rejected.
Origin is validated when an Origin header is present.
File operations are read-only.
File and folder results are filtered through Files.fm access-right checks.
Tool results do not include delete keys, add keys, passwords, storage paths, or private tokens.
Inline file content is capped at 25 MB.
Folder list and search calls have bounded limits.

Files.fm Hosted MCP Connector

Authentication

Capabilities

Tools

filesfm_get_root_folder

filesfm_list_folder

filesfm_get_folder_info

filesfm_get_file_info

filesfm_read_file

filesfm_search_files

filesfm_search_docs

filesfm_get_doc

Resources

Limits

Example JSON-RPC Calls

Client Setup

ChatGPT

Codex

Cursor

Opencode

Claude Clients

Gemini

Modern discovery example

Security and Limits

Related Documentation

`filesfm_get_root_folder`

`filesfm_list_folder`

`filesfm_get_folder_info`

`filesfm_get_file_info`

`filesfm_read_file`

`filesfm_search_files`

`filesfm_search_docs`

`filesfm_get_doc`