Game assets with fal

fal runs hundreds of generative models behind one API key. Use it whenever the mod needs something that doesn't exist yet: a weapon sprite, a boss, a unit rendered from 16 angles, a tileable floor, a laser sound, boss music, a voiced line.

Setup (check once per session)

• Key. Create one at https://fal.ai/dashboard/keys. um fal takes FAL_KEY from the environment first, then the key the human stored with um fal key set (a hidden prompt: the desktop keyring on Linux, through libsecret's secret-tool; an owner-only ~/.secrets/fal-key where there's no secret-tool), then FAL_KEY=... in a .env in the working folder. um fal key status shows which source is used, with keys masked. Never write the key into mod files or configs; um publish check flags leaked keys.

• MCP. fal's hosted MCP server is https://mcp.fal.ai/mcp with header Authorization: Bearer $FAL_KEY. The repo pre-configures it for each agent:

  • Claude Code: .mcp.json
  • Codex: .codex/config.toml
  • Cursor: .cursor/mcp.json
  • VS Code/Copilot: .vscode/mcp.json
  • Gemini CLI: gemini-extension.json
  • OpenCode: opencode.json

  They read FAL_KEY from the agent's environment, and without it the server doesn't connect. If the fal MCP tools are missing, use um fal meanwhile and tell the human. They can start the agent with FAL_KEY set (on Linux, from the keyring: export FAL_KEY="$(secret-tool lookup service fal.ai key api)"), or add fal's OAuth endpoint, which takes a browser sign-in instead of a key:

  • Claude Code: claude mcp add --transport http fal-oauth https://mcp.fal.ai/mcp-relay, then Authenticate it in /mcp
  • Codex: codex mcp add fal-oauth --url https://mcp.fal.ai/mcp-relay, then codex mcp login fal-oauth
  • anything else: a Streamable HTTP server at https://mcp.fal.ai/mcp-relay with OAuth and no header (https://fal.ai/docs/documentation/setting-up/mcp)