Reference

Configuration

Environment variables, endpoints, models, and deployment hooks for the WM Studio MCP.

Environment

All configuration is driven by environment variables. Copy .env.example →.env and set the values below.

Variable	Required	Description	Example
WMSTUDIO_API_URL	required	WM Studio REST base URL the MCP delegates job submission to.	https://wm.studio
FAL_KEY	required	fal.ai API key used by image/video/3D providers.	fal-...
JWT_SECRET	required	Signing key for MCP access tokens. 32+ random bytes in production.	$(openssl rand -base64 32)
MCP_BASE_URL	required	Public URL of this MCP service. Used for OAuth redirects and metadata.	https://your-fly-app.fly.dev
SUPABASE_URL	required	Supabase project URL (same as the WM Studio app).	—
SUPABASE_ANON_KEY	required	Supabase anon key for the user-login bridge.	—
REDIS_URL	required	Redis URL — required in production for OAuth state, jobs, rate limits.	redis://localhost:6379
ENVIRONMENT	optional	Set to `production` to enforce HTTPS.	—
ENFORCE_HTTPS	optional	Force HTTPS even outside production.	—

Authentication

The MCP validates Authorization: Bearer <JWT> withaud=wmstudio-mcp. OAuth 2.1 + PKCE bridges to Supabase as the IdP. The server holds PKCE state in Redis under mcp:oauth:* with a short TTL.

bash

# Mint a dev JWT (uses .env JWT_SECRET)
PYTHONPATH=. python -c "from src.auth import create_test_token; print(create_test_token())"

# Use it
curl -H "Authorization: Bearer $TOKEN" "$MCP_BASE_URL/mcp/"

Models

Tool calls accept a model argument keyed to the provider catalogue. The enabled set is driven by your fal.ai workspace and the WM Studio rate-card. Common ids:

Image: openai/gpt-image-2, fal-ai/flux-2-pro, fal-ai/nano-banana-pro, fal-ai/recraft, gemini
Video: fal-ai/kling-video/v2.5-turbo/pro/text-to-video, fal-ai/kling-video/v2.5-turbo/pro/image-to-video, fal-ai/sora-2/text-to-video/pro, fal-ai/wan, fal-ai/minimax, fal-ai/bytedance
Enhance: topazlabs/video (Video Enhance), built-in upscaler (Upscale Image)

Pass unsupported_model? See errors. The ground truth is src/app/[locale]/dashboard/creative-studio/static-models.ts.

Endpoints

Method	Path	Description
POST	/mcp/	Streamable HTTP MCP endpoint (tools, resources).
GET	/.well-known/oauth-authorization-server	OAuth 2.1 metadata.
GET	/.well-known/oauth-protected-resource	Resource metadata.
GET	/oauth/authorize	Authorization endpoint (server-held PKCE).
POST	/oauth/token	Token endpoint.
GET	/oauth/idp-callback	Supabase IdP callback.
POST	/oauth/register	Dynamic client registration.
GET	/health	Liveness probe.
POST	/webhooks/jobs	Inbound webhook from provider workers (fal.ai callbacks, internal renderers).

Rate limits

Rate-limiting middleware is backed by Redis (src/rate_limiter.py). Per-user windows are applied to /oauth/* and tool execution. Reject responses include standard Retry-After hints.

Deployment

Fly.io and Railway are supported out-of-the-box.

fly launch --no-deploy
fly secrets set JWT_SECRET="$(openssl rand -base64 32)"
fly secrets set WMSTUDIO_API_URL="https://wm.studio"
fly secrets set FAL_KEY="fal-..."
fly secrets set SUPABASE_URL="https://xxx.supabase.co"
fly secrets set SUPABASE_ANON_KEY="your-anon-key"
fly secrets set REDIS_URL="redis://..."
fly secrets set MCP_BASE_URL="https://your-fly-app.fly.dev"
fly secrets set ENVIRONMENT="production"
fly deploy

Variable

Required

Description

Example

WMSTUDIO_API_URL

required

WM Studio REST base URL the MCP delegates job submission to.

https://wm.studio

FAL_KEY

required

fal.ai API key used by image/video/3D providers.

fal-...

JWT_SECRET

required

Signing key for MCP access tokens. 32+ random bytes in production.

$(openssl rand -base64 32)

MCP_BASE_URL

required

Public URL of this MCP service. Used for OAuth redirects and metadata.

https://your-fly-app.fly.dev

SUPABASE_URL

required

Supabase project URL (same as the WM Studio app).

—

SUPABASE_ANON_KEY

required

Supabase anon key for the user-login bridge.

—

REDIS_URL

required

Redis URL — required in production for OAuth state, jobs, rate limits.

redis://localhost:6379

ENVIRONMENT

optional

Set to `production` to enforce HTTPS.

—

ENFORCE_HTTPS

optional

Force HTTPS even outside production.

—

# Mint a dev JWT (uses .env JWT_SECRET) PYTHONPATH=. python -c "from src.auth import create_test_token; print(create_test_token())" # Use it curl -H "Authorization: Bearer $TOKEN" "$MCP_BASE_URL/mcp/"

Models

Tool calls accept a model argument keyed to the provider catalogue. The enabled set is driven by your fal.ai workspace and the WM Studio rate-card. Common ids:

Image: openai/gpt-image-2, fal-ai/flux-2-pro, fal-ai/nano-banana-pro, fal-ai/recraft, gemini

Video: fal-ai/kling-video/v2.5-turbo/pro/text-to-video, fal-ai/kling-video/v2.5-turbo/pro/image-to-video, fal-ai/sora-2/text-to-video/pro, fal-ai/wan, fal-ai/minimax, fal-ai/bytedance

Enhance: topazlabs/video (Video Enhance), built-in upscaler (Upscale Image)

Pass unsupported_model? See errors. The ground truth is src/app/[locale]/dashboard/creative-studio/static-models.ts.

Method

Path

Description

POST

/mcp/

Streamable HTTP MCP endpoint (tools, resources).

GET

/.well-known/oauth-authorization-server

OAuth 2.1 metadata.

GET

/.well-known/oauth-protected-resource

Resource metadata.

GET

/oauth/authorize

Authorization endpoint (server-held PKCE).

POST

/oauth/token

Token endpoint.

GET

/oauth/idp-callback

Supabase IdP callback.

POST

/oauth/register

Dynamic client registration.

GET

/health

Liveness probe.

POST

/webhooks/jobs

Inbound webhook from provider workers (fal.ai callbacks, internal renderers).

fly launch --no-deploy fly secrets set JWT_SECRET="$(openssl rand -base64 32)" fly secrets set WMSTUDIO_API_URL="https://wm.studio" fly secrets set FAL_KEY="fal-..." fly secrets set SUPABASE_URL="https://xxx.supabase.co" fly secrets set SUPABASE_ANON_KEY="your-anon-key" fly secrets set REDIS_URL="redis://..." fly secrets set MCP_BASE_URL="https://your-fly-app.fly.dev" fly secrets set ENVIRONMENT="production" fly deploy