fal Release Notes

Platform MCP Server

fal’s second MCP server — the Platform API MCP — is now available at https://api.fal.ai/v1/mcp/platform. Where the Run MCP lets your AI assistant build with models, this one lets it operate your fal account: connect Claude Code, Cursor, or any MCP-compatible client with your API key and ask “why did my last request to my-app fail?” — your assistant walks the same debugging steps you would.

15 tools: eleven first-class serverless debugging tools covering requests, logs, error analytics, deploy and revision history, runner and queue state, spend, and persistent storage — plus a four-tool discovery gateway that opens up the rest of the Platform API (compute, workflows, keys, account, organization, storage) without bloating your assistant’s context.

Platform MCP Server

fal’s second MCP server — the Platform API MCP — is now available at https://api.fal.ai/v1/mcp/platform. Where the Run MCP lets your AI assistant build with models, this one lets it operate your fal account: connect Claude Code, Cursor, or any MCP-compatible client with your API key and ask “why did my last request to my-app fail?” — your assistant walks the same debugging steps you would.

15 tools: eleven first-class serverless debugging tools covering requests, logs, error analytics, deploy and revision history, runner and queue state, spend, and persistent storage — plus a four-tool discovery gateway that opens up the rest of the Platform API (compute, workflows, keys, account, organization, storage) without bloating your assistant’s context.

• Read-only — it can observe your account but never change it; write operations are listed in the catalog but refuse to execute
• Stateless — your key is sent per-request and never stored, and normal permission and ownership scoping applies
• Free — tool calls are the same Platform API calls you could make directly with your key

Setup guide →

New Serverless Observability APIs

A batch of endpoints rounds out programmatic access to what the dashboard shows about your serverless apps:

GET /v1/serverless/apps — list your deployed apps with live state: active runners, queue size, machine types, and environment. Add expand=endpoints to include each app’s route-level endpoint ids, in the exact form the requests and analytics APIs accept.

GET /v1/serverless/apps/{owner}/{name}/events — operational event history: deployments, configuration changes, and runner lifecycle transitions — the “what changed around this time?” API. Also surfaced in the dashboard’s events timeline.

GET /v1/serverless/apps/{owner}/{name}/revisions — revision history with deployment status, who deployed, and deploy messages and annotations (the API behind the August 3 entry above) — line revision boundaries up against your error timeline to spot a bad deploy.

GET /v1/serverless/apps/{owner}/{name}/runners/history — historical runner counts by state (running, idle, pending, draining) for capacity analysis and incident forensics.

Together with the existing requests, logs, analytics, metrics, and usage APIs, these power the new Platform MCP server — and they’re plain REST endpoints you can call directly with your API key.

GPU Utilization in Runner Telemetry

Runner telemetry now includes a dedicated GPU Utilization chart alongside the existing CPU, memory, and VRAM charts, so you can see how much compute your GPUs are actually doing — not just how much memory they hold.

GPU Utilization reports the average compute utilization across a runner’s GPUs over time, surfaced both as a current stat and a time-series chart in the runner side sheet.
Pair it with VRAM Usage to tell a memory-bound runner apart from a compute-bound one, making it easier to right-size machine types and spot under-utilized GPUs.
Open any runner from the Runners page (Dashboard → Apps → [your-app] → Runners) to view its telemetry. See Runner Analytics for details.

Deploy Messages and Annotations

You can now attach a freeform message and custom annotations to each revision when deploying:

fal deploy my_app.py::MyApp --message "Deploying new version" --annotation GIT_SHA=a1b2c3d4

Messages and annotations are set at deploy time and stay with the revision.
View and search them on the app’s Versions page in the dashboard, or fetch them via the revisions API.
Also available in the Python SDK: client.deploy(..., message=..., annotations={...}).
See Annotating Deployments for details.

App-Level Retry Configuration

Apps can now register a default per-condition retry budget at deploy time with the new retry_config deployment option, using the same format as the X-Fal-Retry-Config request header.

Set it as a class attribute on fal.App or under the app’s table in pyproject.toml.

Applies to all queue-based requests to the app; the app owner can still override it per-request with the X-Fal-Retry-Config header.

Each condition (server_error, timeout, connection_error) keeps an independent budget, bounded by the platform ceiling of 10 total attempts.

See Retries and Error Handling for details.

New Serverless Usage Page

The new Serverless Usage page (Serverless → Usage) provides attributable, dimensioned reporting of serverless compute spend in the dashboard.

Compute reported in machine-seconds , broken down per app, environment, and machine type.

Spend is split by price category: Reserve, Burst, On-Demand, and List. This distinguishes consumption covered by committed reserved capacity from burst overage and undiscounted list-rate usage, supporting reservation sizing and workload placement decisions.

Group by app or by machine type , including a dedicated Usage by machine type view, to identify the deployments and hardware classes driving cost.

Billing-cycle and custom time-range presets are supported. On-demand quotes are reported as a distinct price category, and organization-level reporting now spans both serverless and compute.

This is the same dataset returned by the GET /v1/serverless/usage API, surfaced in the dashboard.

Deploy Existing Docker Servers Without Code Changes

Existing Docker-based servers (ComfyUI, custom APIs) can now be deployed without rewriting them as a fal.App, reducing migration effort from self-hosted infrastructure, Kubernetes, or RunPod.

• Direct Server Mode: set exposed_port in pyproject.toml and fal routes traffic directly to the container port. Existing routes, middleware, and response formats are preserved.
• Prebuilt image references (no Dockerfile required): reference an image already pushed to a registry (image = "my-org/my-server:latest") and override entrypoint / cmd under [tool.fal.apps..image].
• Private registry support: pull from Docker Hub, Google Artifact Registry, or Amazon ECR by supplying registry credentials in the image configuration.

Migration guides are available for external Docker servers and RunPod, along with the pyproject.toml reference and Private Docker Registries.

Serverless Usage API

New GET /v1/serverless/usage endpoint reports your own serverless compute usage — the machine-seconds each of your deployed apps consumed, priced with your machine rates and net of discounts

Break usage down per app, environment, and machine type, with time_series and summary views over any date range and timeframe

Filter by app name with app (exact, one or more) or search (case-insensitive substring) — match a deployed app by name without needing its exact version suffix

Ideal for per-app cost reporting and exporting to your own billing/observability tools

Complements the per-request billable_units on GET /v1/serverless/requests/by-endpoint with an aggregated, time-bucketed view

New Capacity Page

The new Capacity page (Serverless → Capacity) reports GPU consumption against your account limit, providing visibility into available headroom before requests begin queuing.

• Account-wide GPU usage over time, plotted against your limit , with baseline and burst reference lines indicating utilization relative to reserved capacity.
• Per-GPU-type breakdown of capacity consumption by hardware class.
• Approaching-limit and at-limit indicators on runner and app views, with GPU counts shown on runners.
• Request more capacity action for requesting a higher limit.

Per-Condition Retry Configuration

The new X-Fal-Retry-Config request header replaces all-or-nothing retry behavior with a separate retry budget per failure condition, allowing retry policy to be tuned independently for each failure mode.

• Map each retry condition (server_error, timeout, connection_error) to its own retries count (for example, retry transient server errors while disabling retries on timeouts).
• Each condition maintains an independent budget, bounded by the platform ceiling of 10 total attempts.
• Applies to apps you own and takes precedence over status-code defaults. x-fal-no-retry takes precedence when both are set.
• Complements app-level skip_retry_conditions and the per-response X-Fal-Needs-Retry and x-fal-stop-runner controls.

See Retries and Error Handling for the full reference.

Filter and Sort Apps

Managing a large number of serverless apps is now easier with new filtering and sorting controls directly on the apps page.

• Filter by machine type to instantly isolate apps running on specific hardware (e.g., H100, A100, L40) and monitor targeted resource allocation.
• Sort by active runners, GPUs, or queue size to instantly surface the apps consuming the most capacity or backing up with queued requests.

Works in both card view and list view, and stacks with environment and tag filtering so you can find what needs your attention faster.

The runner termination grace period is now configurable, allowing long-running requests to drain and teardown() to complete before SIGKILL, which reduces the risk of dropped work or inconsistent state during scale-down.

The grace period is a shared budget for completing in-flight requests and running teardown(). Use handle_exit() to signal long requests to stop early so cleanup is not skipped.

• termination_grace_period_seconds is configurable up to 1 hour (previously capped at 30 seconds, default 5 seconds).
• The grace period is a shared budget for completing in-flight requests and running teardown(). Use handle_exit() to signal long requests to stop early so cleanup is not skipped.
• keep_alive now applies to both idle-after-request and never-served runners.

See Scale Your Application for details.

The Serverless apps page now opens with an aggregate analytics dashboard that summarizes capacity, traffic, and per-app activity across every app you own in one place.

• GPU and CPU distribution charts visualize how your active runners are split across machine types (H100, A100, L40, B200, CPU types, etc.)
• Live capacity tiles show total Active Runners, Queued Requests, GPUs, and CPUs, each annotated with how many apps contribute to the number
• Status code, request traffic, and concurrent request charts plot aggregate request health over your selected window
• Top Apps lists your highest-volume apps over the window for quick drill-in
• Requests by app is a new stacked chart that breaks aggregate traffic down per app, with a searchable legend you can click to isolate a single app or flip to an Errors view