Skip to main content

Genvoy MCP

Genvoy is a production-grade MCP server for fal.ai media workflows.

It gives AI agents a safe, structured interface to:

  • discover fal.ai models,
  • estimate cost,
  • generate media,
  • compare outputs across models,
  • save outputs to local disk and optionally copy into a repo path.

Genvoy is built for local MCP usage first (BYOK: bring your own key).

What Genvoy Does

Core tools:

  1. search_models - find model IDs before generating (example: search flux).
  2. get_schema - see exactly which inputs a model accepts before calling it.
  3. estimate_cost - check likely cost first so you can decide to proceed or not.
  4. generate - create one output from one prompt and save it to a file path.
  5. generate_batch - create multiple variations on the same model in one call.
  6. generate_compare - run one prompt across multiple models to compare results.
  7. get_job_status - check progress for a previously submitted async request.
  8. cancel_job - stop a queued/running request you no longer want.

Resources:

  1. genvoy://models - quick read-only snapshot of model metadata.
  2. genvoy://recent - quick read-only snapshot of recent usage (Admin key required).

Compatibility bridge tools (added by FastMCP ResourcesAsTools transform):

  1. list_resources - lets clients discover resources even without native resource UI.
  2. read_resource - fetch resource content directly by URI.

Installation Modes

Mode A: Local Source (development)

Run directly from this repo:

uv run python -m genvoy.server

Mode B: Local Installed Package (still local)

Install package locally:

uv tool install .

Then run:

genvoy

Mode C: Published Package via PyPI (still local by default)

After publishing, users can install and run locally (uvx genvoy or local install).

Important: publishing to PyPI does not mean a shared hosted server. It still runs on each user's machine unless you deploy and host a central server yourself.

Local vs Hosted Model

Local MCP (current project focus)

  • each user runs Genvoy locally,
  • each user sets their own FAL_KEY,
  • billing is on each user's fal account.

Hosted shared MCP (optional future architecture)

  • one centralized server serves many users,
  • server key(s) are managed by you,
  • billing and multi-tenant auth become your operational responsibility.

Genvoy currently targets Local MCP.

Requirements

  • Python >=3.11
  • uv
  • fal.ai API key in environment

Optional:

  • fal.ai Admin API key scope if you need genvoy://recent / usage history.

Configuration

Create .env in repo root:

FAL_KEY="Key your_fal_key_here"

If you provide a key without Key prefix, Genvoy auto-normalizes it.

MCP Client Configuration

Use your client's MCP config to run local source:

{
  "mcpServers": {
    "genvoy": {
      "command": "C:\\Users\\HP\\Documents\\DAVID.DEV\\genvoy-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "genvoy.server"],
      "env": {
        "PYTHONPATH": "C:\\Users\\HP\\Documents\\DAVID.DEV\\genvoy-mcp",
        "FAL_KEY": "Key your_fal_key_here"
      }
    }
  }
}

Output Path Behavior (Important)

Genvoy resolves relative output paths from the MCP process working directory (cwd).

What this means:

  • in some IDEs, relative outputs may land in the IDE artifact/workspace folder,
  • not automatically in your project repo root.

Use one of these patterns when you want deterministic placement:

  1. set MCP cwd to your project root,
  2. pass explicit absolute output_path / repo_path,
  3. pass relative repo_path only when cwd is your repo root.

Security behavior:

  • path traversal outside allowed root is blocked with PATH_TRAVERSAL_BLOCKED.

Quick Validation Flow

In your MCP-enabled IDE, run:

  1. search_models for flux
  2. get_schema for fal-ai/flux/dev
  3. estimate_cost for count 1
  4. generate with an output_path
  5. list_resources then read_resource for genvoy://models

If using Admin scope key: 6. read_resource for genvoy://recent

Tool Contract Snapshot

search_models

  • inputs: query, optional category, optional cursor
  • compatibility alias: optional page (mapped to cursor)

get_schema

  • input: model_id

estimate_cost

  • input: model_id, optional count (default 1)

generate

  • input: model_id, prompt, output_path, optional repo_path, optional params
  • output: includes output_path, repo_path, media_type, cost_usd, duration_ms

generate_batch

  • input: model_id, prompt, count, output_dir, optional repo_dir, optional params
  • output: files[] and failed[]

generate_compare

  • input: model_ids[], prompt, output_dir, optional repo_dir, optional params
  • output: files[] and failed[]

get_job_status

  • input: request_id, model_id

cancel_job

  • input: request_id, model_id

Reliability and Safety

  • queue-first fal.ai execution (queue.fal.run)
  • SSE status stream with polling fallback
  • rate-limit mapping (RATE_LIMITED)
  • queue start timeout mapping (QUEUE_START_TIMEOUT)
  • usage scope mapping (ADMIN_KEY_REQUIRED)
  • non-blocking I/O (httpx async + aiofiles)
  • output filename collision handling (_1, _2, ...)

Development Commands

uv run ruff check .
uv run mypy genvoy
uv run pytest --cov --cov-report=term-missing

Documentation Map

License

MIT

Metadata

Release files for genvoy 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for genvoy 0.1.0
File Size Uploaded Provenance Actions
genvoy-0.1.0.tar.gz 119.9 kB With provenance Details for genvoy-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for genvoy 0.1.0
File Interpreter ABI Platform Actions
genvoy-0.1.0-py3-none-any.whl Python 3 none any Details for genvoy-0.1.0-py3-none-any.whl

Total release size: 136.2 kB

Release files / genvoy-0.1.0.tar.gz

Download URL genvoy-0.1.0.tar.gz
Size 119.9 kB
Tags Source
SHA-256 checksum
How to use checksums
2d9356aee04600c5f75312cdb08e72351efa82a25ef5819c71fae89418e58dd5
BLAKE2b-256 checksum
How to use checksums
1757ded44d734102fdf45b2be68e29e8cef0276986c8c2fef41e9f427d344026
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 25, 2026.

Transparency log

Release files / genvoy-0.1.0-py3-none-any.whl

Download URL genvoy-0.1.0-py3-none-any.whl
Size 16.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f939a96c709c06de828f7e145d58b0b57c9c1165e58a888ab0f2db0bb0e9dbe3
BLAKE2b-256 checksum
How to use checksums
d74e96ac47ab822774e3f4da5b9d63a159cd0a748db3be0dfd3f8de4f434bd57
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 25, 2026.

Transparency log

Security for genvoy 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for genvoy-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Feb 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page