Skip to main content
Glama
thenavidm

fal.ai MCP Server

by thenavidm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Set file ACL

set_storage_file_acl
Destructive

Replace the access control list of a fal CDN file to set default allow, forbid, or hide decisions and per-user overrides, controlling whether the file is public or restricted.

Instructions

Replaces the Access Control List of a fal CDN file.

The ACL consists of a default decision (allow, forbid, or hide) plus optional per-user rules that override the default. Rule users may be specified by nickname or user ID. Setting default to allow with no rules makes the file public; forbid or hide restricts it to the rules you provide.

Rules referencing users that do not exist are dropped. The response reflects the ACL actually applied, so verify it contains the rules you sent.

Authentication: Required. The API key must have the assets:write permission.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
urlYesFull URL of the fal CDN file, as returned by the upload APIs (https://v3.fal.media/files/b/<id>/<filename>). Must not contain query parameters.
rulesNo
accountNoExact private account key profile label, not an authenticated provider owner ID.
confirmNoSet true only when the user asked for exactly this action.
defaultNoFallback decision when no user-specific rule matches
payloadNoComplete native JSON body, mutually exclusive with flat body flags and payload_file. Use schema for union bodies.
payload_fileNoAbsolute regular non-symlink private JSON file, at most 1 MiB. Cannot mix with other body inputs.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changedv3.0.1
    • addedInput schema / $defs
      Added value: +{
+  "rules": {
+    "default": [],
+    "description": "User-specific overrides to the default decision",
+    "items": {
+      "additionalProperties": false,
+      "description": "A per-user access control rule",
+      "properties": {
+        "decision": {
+          "description": "Access decision applied to this user",
+          "enum": [
+            "allow",
+            "forbid",
+            "hide"
+          ],
+          "type": "string"
+        },
+        "user": {
+          "description": "User nickname or user ID the rule applies to",
+          "minLength": 1,
+          "type": "string"
+        }
+      },
+      "required": [
+        "user",
+        "decision"
+      ],
+      "type": "object"
+    },
+    "type": "array"
+  }
+}
    • changedInput schema / properties / confirm / description
      Previous value: -"Must be true for the requested mutation, paid work or private output file."New value: +"Set true only when the user asked for exactly this action."
    • addedInput schema / properties / payload / properties / rules / $ref
      Added value: +"#/$defs/rules"
    • removedInput schema / properties / payload / properties / rules / default
      Removed value: -[]
    • removedInput schema / properties / payload / properties / rules / description
      Removed value: -"User-specific overrides to the default decision"
    • removedInput schema / properties / payload / properties / rules / items
      Removed value: -{
-  "additionalProperties": false,
-  "description": "A per-user access control rule",
-  "properties": {
-    "decision": {
-      "description": "Access decision applied to this user",
-      "enum": [
-        "allow",
-        "forbid",
-        "hide"
-      ],
-      "type": "string"
-    },
-    "user": {
-      "description": "User nickname or user ID the rule applies to",
-      "minLength": 1,
-      "type": "string"
-    }
-  },
-  "required": [
-    "user",
-    "decision"
-  ],
-  "type": "object"
-}
    • removedInput schema / properties / payload / properties / rules / type
      Removed value: -"array"
    • addedInput schema / properties / rules / $ref
      Added value: +"#/$defs/rules"
    • removedInput schema / properties / rules / default
      Removed value: -[]
    • removedInput schema / properties / rules / description
      Removed value: -"User-specific overrides to the default decision"
    • removedInput schema / properties / rules / items
      Removed value: -{
-  "additionalProperties": false,
-  "description": "A per-user access control rule",
-  "properties": {
-    "decision": {
-      "description": "Access decision applied to this user",
-      "enum": [
-        "allow",
-        "forbid",
-        "hide"
-      ],
-      "type": "string"
-    },
-    "user": {
-      "description": "User nickname or user ID the rule applies to",
-      "minLength": 1,
-      "type": "string"
-    }
-  },
-  "required": [
-    "user",
-    "decision"
-  ],
-  "type": "object"
-}
    • removedInput schema / properties / rules / type
      Removed value: -"array"
  2. First observedv2.0.0

TDQS

A4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing the auth requirement (API key needs `assets:write`), the silent-drop behavior for rules referencing nonexistent users, and the fact that the response reflects the ACL actually applied so callers should verify it. These are exactly the failure modes an agent needs for a destructive, non-idempotent write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then progressively deeper detail, ending with a clearly bolded Authentication line. Every sentence carries information, though the default/rules explanation partially restates what the schema enum descriptions already convey.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter destructive mutation with nested objects and no output schema, the description covers the important operational facts: auth scope, silent rule dropping, and the need to verify the returned ACL. It omits guidance on confirm/account/payload_file, but those are documented in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 86%, so the baseline is 3, but the description adds real semantic value: the default/rules interplay ('allow with no rules makes the file public; forbid or hide restricts it to the rules you provide') and that rule users may be a nickname or user ID. The confirm/account/payload_file parameters are left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Replaces the Access Control List of a fal CDN file.' It is clearly distinct from the read-side sibling get_storage_file_acl by the word 'Replaces', though it never names the sibling explicitly or states that it is the write counterpart.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied by the semantics of replacement and the explanation of what each default decision does. There is no explicit 'use this when...' guidance, no mention of get_storage_file_acl as the read alternative, and no statement of prerequisites beyond the auth note.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools