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:
search_models- find model IDs before generating (example: searchflux).get_schema- see exactly which inputs a model accepts before calling it.estimate_cost- check likely cost first so you can decide to proceed or not.generate- create one output from one prompt and save it to a file path.generate_batch- create multiple variations on the same model in one call.generate_compare- run one prompt across multiple models to compare results.get_job_status- check progress for a previously submitted async request.cancel_job- stop a queued/running request you no longer want.
Resources:
genvoy://models- quick read-only snapshot of model metadata.genvoy://recent- quick read-only snapshot of recent usage (Admin key required).
Compatibility bridge tools (added by FastMCP ResourcesAsTools transform):
list_resources- lets clients discover resources even without native resource UI.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:
- set MCP
cwdto your project root, - pass explicit absolute
output_path/repo_path, - pass relative
repo_pathonly whencwdis 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:
search_modelsforfluxget_schemaforfal-ai/flux/devestimate_costfor count1generatewith anoutput_pathlist_resourcesthenread_resourceforgenvoy://models
If using Admin scope key:
6. read_resource for genvoy://recent
Tool Contract Snapshot
search_models
- inputs:
query, optionalcategory, optionalcursor - compatibility alias: optional
page(mapped tocursor)
get_schema
- input:
model_id
estimate_cost
- input:
model_id, optionalcount(default1)
generate
- input:
model_id,prompt,output_path, optionalrepo_path, optionalparams - output: includes
output_path,repo_path,media_type,cost_usd,duration_ms
generate_batch
- input:
model_id,prompt,count,output_dir, optionalrepo_dir, optionalparams - output:
files[]andfailed[]
generate_compare
- input:
model_ids[],prompt,output_dir, optionalrepo_dir, optionalparams - output:
files[]andfailed[]
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 (
httpxasync +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
- System architecture:
docs/architecture.md - Build/test/release phases:
docs/setup.md - Product-level behavior overview:
docs/overview.md
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.