# 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:

```text
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

## Authentication

Private file tools require an API access token:

```http
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.

## Capabilities

Supported JSON-RPC methods:

- `initialize`
- `tools/list`
- `tools/call`
- `resources/list`
- `resources/read`
- `resources/templates/list`

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

## 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:

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

### `filesfm_get_folder_info`

Returns metadata for one visible folder.

Arguments:

```json
{
  "folder_hash": "abc123"
}
```

### `filesfm_get_file_info`

Returns metadata for one visible file.

Arguments:

```json
{
  "file_hash": "abc123"
}
```

### `filesfm_read_file`

Reads one visible file when the token has download rights.

Arguments:

```json
{
  "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:

```json
{
  "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:

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

## 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`

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.

## Example JSON-RPC Calls

Initialize:

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

Search docs:

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

Read a file:

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

## Client Setup

### Codex

Example `config.toml` remote MCP server:

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

Environment variable value:

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

### Cursor

Example `.cursor/mcp.json`:

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

### Opencode

Example remote MCP configuration:

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

### Claude Clients

For Claude clients that support remote MCP servers or connectors, add `https://api.files.fm/api/mcp` as the server URL and configure:

```http
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.

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

## Related Documentation

- [API overview](README.md)
- [REST API V2 reference](filesfm_api_v2.md)
- [DMS API](filesfm_api_dms.md)