Skip to content

Configuration

Configuration is loaded from environment variables or .env by Pydantic Settings. Copy .env.example to .env. Empty values are ignored.

.env is resolved relative to the server’s working directory. Most MCP clients set that correctly from their server configuration, so this is rarely the problem. When a client cannot, it finds no .env, and the server starts with no provider credentials and registers only the always-on job and artifact tools — set ARK_MCP_ENV_FILE to an absolute path for that case, or launch the server with its working directory at the repository root (for example uv --directory /path/to/ark-mcp run python -m ark_mcp). The server logs a no_provider_credentials_configured warning at startup when it happens; if a client is missing tools and that warning is absent, look at troubleshooting instead.

Variable Default Purpose
ARK_MCP_ENV_FILE .env Absolute path to the env file, for clients that cannot control the working directory
Variable Default Purpose
BYTEPLUS_MODELARK_API_KEY empty Enables Seedream, Seedance, and Seed 2.1 understanding; sent as Bearer auth
BYTEPLUS_SEED_SPEECH_API_KEY empty Enables Seed Audio and speech-to-text; sent as X-Api-Key
BYTEPLUS_VOD_MEDIAKIT_API_KEY empty Enables MediaKit enhancement, transcode, subtitle burn-in/removal, audio-separation, and poll tools; sent as Bearer auth
BYTEPLUS_CV_API_KEY empty BytePlus Vision AI Bearer key for OmniHuman; tools also need BYTEPLUS_OMNIHUMAN_ENABLED=true
BYTEPLUS_MODELARK_BASE_URL AP Southeast ModelArk URL HTTPS data-plane base URL
BYTEPLUS_SEED_AUDIO_BASE_URL AP Southeast Seed Speech URL HTTPS service base URL
BYTEPLUS_VOD_MEDIAKIT_BASE_URL https://mediakit.ap-southeast-1.bytepluses.com/api/v1 HTTPS VOD AI MediaKit convenience-endpoint base URL
SEEDREAM_DEFAULT_MODEL dola-seedream-5-5-261028 Default image model/endpoint ID (Seedream 5.5; account authorization required)
SEEDREAM_PROMPT_OPTIMIZATION_MODE standard Mode 5.0 Pro sends when a caller omits prompt_optimization: standard (prompt-following quality) or fast (lower latency). Both are provider-accepted; an explicit per-call value wins
SEEDANCE_DEFAULT_MODEL dreamina-seedance-2-5-260628 Default video model/endpoint ID used by seedance_create_task when model is omitted (Seedance 2.5; was 2.0 before the tool consolidation, see the upgrade note)
SEED_UNDERSTANDING_DEFAULT_MODEL dola-seed-2-1-turbo-260628 Default understanding model/endpoint ID. Set to dola-seed-evolving to use the latest Pro-tier model (auto-resolves to family pro, no SEED_UNDERSTANDING_MODEL_FAMILY needed)
SEEDREAM_MODEL_FAMILY empty Family for a custom default: seedream_5_5, pro, lite, or 4x
SEEDANCE_MODEL_FAMILY empty Family for a custom default: standard, fast, mini, seedance_2_5 (through 4K), or seedance_2_5_flash (480p/720p, no Draft)
SEED_UNDERSTANDING_MODEL_FAMILY empty Family for a custom default: pro or turbo
SEEDREAM_MODEL_BINDINGS empty JSON list of {model_id, family} bindings
SEEDANCE_MODEL_BINDINGS empty JSON list of {model_id, family} bindings
SEED_UNDERSTANDING_MODEL_BINDINGS empty JSON list of {model_id, family} bindings
SEED_AUDIO_UNDERSTANDING_MODEL seed-2-0-lite-260428 Model/endpoint ID used by seed_audio_understand. Any ModelArk model that accepts Chat Completions input_audio parts with deep thinking works; change it when a newer audio-capable model ships
BYTEPLUS_MODELARK_3D_ENABLED false Feature flag for 3D generation (Hyper3D + Hitem3d); reuses the ModelArk key, disabled by default
HYPER3D_DEFAULT_MODEL hyper3d-gen2 Default Hyper3D model/endpoint ID
HITEM3D_DEFAULT_MODEL hitem3d-2-0 Default Hitem3d model/endpoint ID
SEED3D_MODEL_BINDINGS empty JSON list of {model_id, family} bindings (hyper3d or hitem3d)
BYTEPLUS_OMNIHUMAN_ENABLED false Feature flag for OmniHuman 2.0 (omnihuman_* tools); requires BYTEPLUS_CV_API_KEY
BYTEPLUS_CV_BASE_URL https://openapi.cv.bytepluses.com HTTPS Vision AI base URL
BYTEPLUS_OMNIHUMAN_REQ_KEY realman_avatar_picture_omni20_cv Service identifier sent as req_key; change only if BytePlus issues a new one

The recognized built-in IDs have known families. A custom ID must be bound explicitly; the server does not infer capabilities from substrings in an ID. For example:

SEEDREAM_DEFAULT_MODEL=my-image-endpoint
SEEDREAM_MODEL_BINDINGS=[{"model_id":"my-image-endpoint","family":"pro"}]

The default is now Seedream 5.5 (dola-seedream-5-5-261028). This changes only deployments that omit SEEDREAM_DEFAULT_MODEL; existing explicit defaults stay unchanged. Discovery reflects configured models, not provider authorization. Accounts without 5.5 access should retain 5.0 Pro:

SEEDREAM_DEFAULT_MODEL=dola-seedream-5-0-pro-260628

Both built-in IDs resolve without a family setting. For a custom 5.5 endpoint, set SEEDREAM_MODEL_FAMILY=seedream_5_5. If SEEDREAM_MODEL_BINDINGS contains only older models and no explicit default, startup fails until the default is set to a bound ID or a 5.5 binding is added. To offer both:

SEEDREAM_DEFAULT_MODEL=dola-seedream-5-5-261028
SEEDREAM_MODEL_BINDINGS=[{"model_id":"dola-seedream-5-5-261028","family":"seedream_5_5"},{"model_id":"dola-seedream-5-0-pro-260628","family":"pro"}]

5.5 uses PNG output when omitted and accepts transparent text-to-image. SEEDREAM_PROMPT_OPTIMIZATION_MODE remains specific to 5.0 Pro; explicit prompt_optimization="standard" is accepted on 5.5, while fast is rejected even when the Pro-only operator setting is fast. Omitted 5.5 optimization uses the provider’s standard default. Background defaults to auto on 5.5. See image model limits.

Read seed-health://status to confirm the effective Seedream default model and binding family. The resource also reports whether background-job local exports have an absolute OUTPUT_ROOTS entry (comma-separated paths). It never reveals root paths or credentials. These are configuration diagnostics only: they do not probe provider authorization, check filesystem readiness, or replace the request’s destination preflight. Client MCP roots are unavailable inside jobs. Seedream dry-run preview.price_source distinguishes a cached account image rate (catalog) from the built-in fallback (builtin); neither is actual billing.

SEEDANCE_DEFAULT_MODEL now defaults to Seedance 2.5 (dreamina-seedance-2-5-260628) instead of 2.0. Every Seedance model is called through the single seedance_create_task tool, and the default model must be one of the bound IDs.

Your configuration Result after upgrading
No SEEDANCE_MODEL_BINDINGS, no SEEDANCE_DEFAULT_MODEL Regular Seedance 2.5 and Flash are bound automatically; regular 2.5 is the default
SEEDANCE_DEFAULT_MODEL set explicitly, bindings empty The selected model remains the default; Flash is also bound unless it is the selected default
SEEDANCE_MODEL_BINDINGS lists only a Seedance 2.0 model and SEEDANCE_DEFAULT_MODEL is unset Startup fails with Seedance default model 'dreamina-seedance-2-5-260628' is missing from its bindings. Set the default model env var to one of the bound IDs: [...]

Fix for the failing case: set SEEDANCE_DEFAULT_MODEL to the bound 2.0 ID to keep 2.0 as the default, or add a 2.5 binding to use the new default:

# Keep Seedance 2.0 as the default
SEEDANCE_DEFAULT_MODEL=dreamina-seedance-2-0-260128
SEEDANCE_MODEL_BINDINGS=[{"model_id":"dreamina-seedance-2-0-260128","family":"standard"}]
# Or bind both and default to 2.5
SEEDANCE_MODEL_BINDINGS=[{"model_id":"dreamina-seedance-2-0-260128","family":"standard"},{"model_id":"dreamina-seedance-2-5-260628","family":"seedance_2_5"}]

Callers then choose a model per request with model, taking an exact ID from ark_list_models(kind='video').

All resolutions use dreamina-seedance-2-5-260628 and family seedance_2_5. Select resolution="4k" on seedance_create_task; no extra feature flag, model binding, or tool is needed.

The separate Premium model, family, service entry, and configuration settings have been removed without a compatibility layer. Remove BYTEPLUS_MODELARK_SEEDANCE_2_5_PREMIUM_ENABLED and SEEDANCE_2_5_PREMIUM_MODEL from configuration and replace any seedance_2_5_premium binding with the current 2.5 model and family. There is no automatic alias or rerouting of old model IDs.

Draft previews remain 480p and Draft-to-final rendering remains 1080p; 4K currently applies to ordinary generation, not Draft promotion. Static video cost previews do not account for resolution or duration.

Flash uses dreamina-seedance-2-5-flash-261115, family seedance_2_5_flash, through the same seedance_create_task tool, ModelArk key, host, and task lifecycle. It supports 480p/720p, 4-30 seconds, 10 image / 5 video / 5 audio references, audio-only input, reference/edit/extend task types, and MP4/MOV. It does not support 1080p, 4K, draft, or draft_task_id.

With empty bindings, Flash is added alongside the selected default. Regular 2.5 remains the default for omitted model. A non-empty SEEDANCE_MODEL_BINDINGS remains authoritative; add Flash explicitly there:

SEEDANCE_MODEL_BINDINGS=[{"model_id":"dreamina-seedance-2-5-260628","family":"seedance_2_5"},{"model_id":"dreamina-seedance-2-5-flash-261115","family":"seedance_2_5_flash"}]

To use a custom Flash endpoint, bind its ID to seedance_2_5_flash. Listing the model does not prove provider activation or account entitlement. No new feature flag is required. Flash cost previews currently reuse the static 2.5 per-task fallback, not its token-based provider price.

Credentials are startup-only. If a provider key is absent, its tools are not registered. Specifically, vod_enhance_video is registered independently when BYTEPLUS_VOD_MEDIAKIT_API_KEY is non-empty; it does not require the ModelArk key. Provider base URLs must use HTTPS, include a hostname, and must not contain embedded credentials.

Variable Default Purpose
MCP_TRANSPORT stdio stdio or Streamable http
MCP_HOST 127.0.0.1 HTTP bind address
MCP_PORT 3000 HTTP listen port
MCP_ALLOWED_HOSTS loopback hosts Comma-separated accepted Host headers
MCP_ALLOWED_ORIGINS empty Comma-separated accepted browser Origins
MCP_HTTP_MAX_BODY_BYTES 314572800 (300 MiB) Maximum HTTP request body; sized to inline the largest supported Base64 media upload (200 MiB video inflates ~4/3x). A smaller value logs a warning at startup (large inlined uploads will 413).
READINESS_CHECK_PROVIDERS false When true, /ready also checks provider connectivity
READINESS_PROVIDER_TIMEOUT_SECONDS 2.0 Per-provider timeout for readiness checks
RATE_LIMIT_RPM 0 Max HTTP requests per minute per client IP; 0 disables
RATE_LIMIT_BURST 0 Token bucket burst size; 0 defaults to RATE_LIMIT_RPM
RATE_LIMIT_TRUST_PROXY_HEADERS false Trust the first X-Forwarded-For entry for rate-limit keys; enable only behind a trusted proxy
MCP_AUTH_MODE local local or api_key; Docker, Compose and Terraform default to api_key
MCP_API_KEY_SHA256 empty Required for api_key: lowercase SHA-256 hex digest of the shared MCP key, never the raw key

FASTMCP_TRANSPORT, FASTMCP_HOST, and FASTMCP_PORT are accepted as aliases for the corresponding MCP_* transport settings.

local auth is accepted only for stdio or loopback HTTP. Binding HTTP to a non-loopback address fails closed unless api_key mode and a valid digest are configured. API key mode assigns one shared-team tenant/principal with ordinary tool permissions, a shared budget and shared data access, excluding account-wide admin scopes. See shared-key setup and rotation. The internal tenant claim key is fixed to tenant_id, not an operator setting. FastMCP enforces the fixed ordinary scope allowlist:

  • seed:audio:generate
  • seedream:generate
  • seedance:create
  • gen:read, gen:delete (gen_task_* tools for Seedance and 3D tasks)
  • seed:asr:transcribe
  • understanding:read
  • hyper3d:create, hitem3d:create
  • omnihuman:create, omnihuman:read, omnihuman:cancel
  • vod:enhance
  • vod:transcode
  • vod:subtitle:add
  • vod:subtitle:remove
  • vod:read
  • vod:extract
  • media:upload
  • media:presign
  • artifacts:read

Breaking change: jwt mode is rejected. Retired MCP_JWT_*, MCP_TENANT_CLAIM and MCP_PUBLIC_BASE_URL settings are not used. There is no automatic ownership transfer. Preserve SQLite, Redis, artifacts and the snapshot encryption key; follow the migration procedure.

The speech_to_text tool is registered when BYTEPLUS_SEED_SPEECH_API_KEY is set — the same key that enables Seed Audio (TTS). It submits audio via HTTP, polls until transcription is complete, and returns the complete TranscriptionResult through a required background job, submitted through the ordinary ark_job_* tools or native MCP task augmentation on a task-capable client. Audio input accepts URL, Base64, or a local file path (stdio only).

Variable Default Purpose
BYTEPLUS_SEED_SPEECH_API_KEY empty Enables Seed Audio + speech-to-text; sent as X-Api-Key header
SEED_SPEECH_ASR_BASE_URL https://voice.ap-southeast-1.bytepluses.com Seed Speech ASR HTTP host
SEED_SPEECH_ASR_POLL_INTERVAL_SECONDS 3.0 Seconds between ASR query polls
SEED_SPEECH_ASR_POLL_MAX_SECONDS 600.0 Maximum total seconds to wait for ASR result

Fixed team scope for speech-to-text:

  • seed:asr:transcribe

vod_enhance_video is registered when BYTEPLUS_VOD_MEDIAKIT_API_KEY is set. The tool supports the fast, standard, and professional enhancement tiers with target resolutions from 240p to 8K (4K for fast) and defaults to professional/4k/high/24 fps. It serializes the project label upstream as case-sensitive Project for standard/professional. Submission returns an asynchronous task ID and operation="enhance" for vod_get_task, the single MediaKit poller, which returns and best-effort persists completed outputs. The submit POST is not retried automatically. Convenience-endpoint pricing is not yet confirmed, so the tool does not emit a cost estimate.

vod_transcode_video and vod_get_task are also registered when BYTEPLUS_VOD_MEDIAKIT_API_KEY is set. vod_transcode_video submits an async transcoding task (codec, container format, scaling, bitrate, frame rate, HDR); vod_get_task with operation="transcode" polls it and best-effort persists the completed output. The transcode request/status contract is verified from the official AI MediaKit API reference; the output URL hostname (*.byteplusvod.com) is confirmed and trusted for durable persistence. queue_id/Project request params remain unverified and are not exposed.

vod_add_subtitles and vod_remove_subtitles (polled with vod_get_task, operation="add_subtitles" or "remove_subtitles") use the same API key. Addition accepts a public HTTPS SRT, VTT, or ASS file or inline timed cues and burns them into the output video. Removal defaults to dialogue-subtitle mode; the broader text mode may also erase titles, labels, or watermarks. Both submit asynchronously, use client_token to reconcile ambiguous submissions, and preserve the provider URL when optional durable persistence is skipped or fails. The optional project and removal model_version fields are legacy convenience-endpoint extensions and are omitted unless explicitly supplied.

vod_separate_audio and vod_get_task are registered when BYTEPLUS_VOD_MEDIAKIT_API_KEY is set, sharing the same Bearer-authenticated convenience surface as enhancement and transcoding.

vod_separate_audio submits a POST /api/v1/tools/separate-voice task from a public HTTPS audio_url or video_url (exactly one) plus an optional scene (Audio default, Music, Drama, Narrate) and output_format (aac default, mp3, wav, m4a, flac). vod_get_task with operation="separate_audio" polls GET /api/v1/tasks/{task_id} and returns each separated track (voice, background, music, sfx) as an output with its expiring source_url (valid 24 hours) plus a durable artifact reference when best-effort persistence succeeds. An output_path directory receives every track.

The ark_asset_* tools are registered only when both BYTEPLUS_MODELARK_ACCESS_KEY and BYTEPLUS_MODELARK_SECRET_KEY are set; they do not need BYTEPLUS_MODELARK_API_KEY. Seedance asset:// references need only the API key. See assets.md.

Variable Default Description
BYTEPLUS_MODELARK_ACCESS_KEY empty BytePlus IAM access key (AKLT… long-term or AKTP… STS) for signed ModelArk OpenAPI calls
BYTEPLUS_MODELARK_SECRET_KEY empty Matching secret key; must be set together with the access key
BYTEPLUS_MODELARK_SESSION_TOKEN empty STS session token, required for AKTP… keys (sent as signed X-Security-Token)
BYTEPLUS_MODELARK_PRICING_REFRESH_SECONDS 86400 Background account-price refresh interval when AK/SK exists; 0 disables. Values below 60 seconds are clamped to 60; snapshots expire after twice the effective interval
BYTEPLUS_MODELARK_OPENAPI_BASE_URL https://ark.ap-southeast-1.byteplusapi.com ModelArk OpenAPI host (HTTPS)
BYTEPLUS_MODELARK_REGION ap-southeast-1 Signing region
BYTEPLUS_MODELARK_PROJECT_NAME default Default project for groups and assets; must match the inference endpoint’s project
BYTEPLUS_MODELARK_ASSETS_ALLOW_DELETE false Registers the irreversible ark_asset_delete tool (assets and groups)
BYTEPLUS_MODELARK_ASSET_CREATE_QPM 3 Client-side CreateAsset pacing; set to your tier (3 Entry, 120 Advanced, 300 Premium)
BYTEPLUS_MODELARK_ASSET_VERIFY_CALLBACK_URL empty Default HTTPS redirect for real-person verification
BYTEPLUS_MODELARK_ASSET_REFERENCE_MODE off Seedream / Seed Audio asset:// handling: off rejects, resolve swaps in the temporary asset URL (experimental; needs AK/SK)
SEEDANCE_ASSET_PREFLIGHT true With AK/SK, check asset:// references with GetAsset before a billed Seedance submit

Account-wide asset scopes (assets:read, assets:write, assets:verify, assets:delete) are excluded from shared-key HTTP. Use trusted local stdio for asset administration; configuring AK/SK does not grant remote access.

Variable Default Description
BYTEPLUS_MODELARK_MODERATION_ENABLED false Registers foreground-only ark_moderation_get when complete ModelArk AK/SK is configured

Reuses the OpenAPI host, signing region and AK/SK above; temporary credentials also need BYTEPLUS_MODELARK_SESSION_TOKEN. A ModelArk Bearer key is not required. The account needs Advanced Creation Rights, whitelist activation and IAM GetModerationResult. Discovery’s moderation service and health’s Moderation lookup configured report configuration only, not entitlement.

This is account-wide trusted stdio/local-mode loopback access, not tenant-scoped access. moderation:read is not granted to shared-key HTTP, even with the flag enabled. AK/SK also register asset tools and enable the pricing refresher; for isolated lookup set BYTEPLUS_MODELARK_PRICING_REFRESH_SECONDS=0, without broadening a moderation-only IAM policy. The fixed ten-lookups-per-rolling-minute guard is independent of HTTP rate limits; live success remains unverified. See moderation.md for eligibility, validation and quota bounds.

The media_upload and media_presign tools are registered when the selected object-storage backend is configured. media_upload uploads 1-50 files to a private bucket and returns a presigned HTTPS GET URL per file; media_presign generates fresh presigned URLs for 1-100 existing objects without re-uploading. Use OBJECT_STORAGE_BACKEND to select tos (default) or s3.

Variable Default Purpose
MEDIA_UPLOAD_BATCH_MAX_BYTES 524288000 (500 MiB) Maximum total decoded bytes in one media_upload call (all items); checked before any upload starts, and an oversized call fails as a whole
Variable Default Purpose
TOS_ACCESS_KEY empty TOS access key (AK)
TOS_SECRET_KEY empty TOS secret key (SK)
TOS_SECURITY_TOKEN empty Optional temporary security token
TOS_BUCKET empty Target bucket name
TOS_REGION ap-southeast-1 TOS region
TOS_ENDPOINT tos-ap-southeast-1.bytepluses.com TOS API endpoint
TOS_PRESIGN_TTL_SECONDS 1800 Presigned URL validity in seconds (60–604800)
Variable Default Purpose
S3_ACCESS_KEY empty S3 access key ID
S3_SECRET_KEY empty S3 secret access key
S3_BUCKET empty Target bucket name
S3_REGION us-east-1 AWS region
S3_ENDPOINT empty Custom endpoint for S3-compatible storage (MinIO, R2)
S3_PRESIGN_TTL_SECONDS 1800 Presigned URL validity in seconds (60–604800)
OBJECT_STORAGE_BACKEND tos Select active backend: tos or s3

AK and SK must both be set or both be empty. The bucket must remain private; presigned URLs grant temporary read access to individual objects. When S3_ENDPOINT is set, path-style addressing is used automatically for S3-compatible storage.

Variable Default Purpose
ARTIFACT_BACKEND filesystem filesystem (local disk) or object_storage (TOS/S3)
STATE_BACKEND sqlite Task ownership/budget/cache backend; only sqlite (single instance) is implemented
ARTIFACT_DIR ~/.ark-mcp/artifacts Media, metadata, ownership, and budget state
ARTIFACT_TTL_SECONDS 604800 Artifact retention, in seconds
ARTIFACT_SWEEP_INTERVAL_SECONDS 3600 Interval between background artifact/state expiry sweeps
STATE_PRUNE_MAX_AGE_DAYS 30 Max age for ownership/budget/cache rows before pruning; at least 14 for authenticated HTTP with regular Seedance 2.5 enabled
MCP_INLINE_MEDIA_MAX_BYTES 8388608 Maximum inline MCP media size
ARTIFACT_DOWNLOAD_TIMEOUT_SECONDS 120 Timeout for each attempt to download provider output into artifact storage (filesystem and object-storage backends)
ARTIFACT_DOWNLOAD_MAX_ATTEMPTS 3 Attempts (1-10) for a retryable output download (timeouts, network errors, 408/429/5xx), with 1s, 2s, 4s, … backoff. Expired, untrusted, or oversized sources are never retried
ARTIFACT_INLINE_FALLBACK_MAX_BYTES 8388608 (8 MiB) When inline Base64 output (Seed Audio, Seedream b64_json) cannot be stored, return it inline in ArtifactRef.fallback_data up to this decoded size; 0 disables
PROVIDER_MAX_CONCURRENCY 5 Process-wide slots per provider
PRINCIPAL_MAX_CONCURRENCY 3 Shared slots across the whole team on authenticated HTTP; skipped in local mode
DAILY_BUDGET_USD 0 Per-principal UTC daily estimate limit, team-wide on shared-key HTTP; zero records only
PERSISTENCE_CACHE_MAX_SIZE 10000 Max cached provider task IDs in artifact-resolution cache
PERSISTENCE_CACHE_TTL_SECONDS 86400 TTL for cached task-to-artifact mappings (seconds)

Authenticated HTTP servers with ModelArk credentials and any regular seedance_2_5 binding (including custom or non-default models) require STATE_PRUNE_MAX_AGE_DAYS >= 14 to retain Draft ownership throughout the promotion window. Shorter values fail at startup; increase existing overrides or keep the 30-day default. Flash-only, legacy-only, local, and disabled ModelArk configurations retain the one-day minimum. Increasing retention does not recover already-pruned ownership rows; missing ownership remains denied.

A billed output is never dropped because storage failed; see Artifacts.

The filesystem backend enforces principal and tenant ownership. It is suitable for one process. Multiple replicas require shared artifact, task-ownership, budget, cache, and limiter implementations before horizontal scaling is safe.

Variable Default Purpose
OUTPUT_ROOTS empty Comma-separated absolute directories where stdio tools may write files (output_path, output_dir, save_to, destination_path)

The client’s MCP roots (roots/list) take precedence when the client provides them; OUTPUT_ROOTS is the fallback. With neither, local path writing is disabled and those fields are rejected. Background jobs (ark_job_submit) run in a worker with no MCP session and therefore no MCP roots, so local writes from a job always use OUTPUT_ROOTS; set it whenever jobs should write files. Path writing is stdio-only. See Security.

Variable Default Purpose
BYTEPLUS_CONNECT_TIMEOUT_MS 10000 Provider connection timeout
BYTEPLUS_REQUEST_TIMEOUT_MS 600000 Full provider request timeout
SEED_UNDERSTANDING_TIMEOUT_MS unset (uses BYTEPLUS_REQUEST_TIMEOUT_MS) Request timeout for seed_understand and seed_audio_understand chat completions. Deep thinking is always on, so long analyses may need more than the general request timeout
FASTMCP_DOCKET_URL memory:// FastMCP background-task backend used by generation, transcription, upload, provider submission, understanding, and optional media-persistence calls; Redis can retain task state across restarts of the same single-replica deployment; it does not make SQLite state horizontally scalable
FASTMCP_TASKS_ENCRYPTION_KEY unset Required for API-key-authenticated Redis task backends; use at least 32 random characters and keep the same key across restarts
FASTMCP_DOCKET_CONCURRENCY 10 Maximum active background tasks per worker; provider/principal limits still apply
ARK_LOG_LEVEL INFO DEBUG, INFO, WARNING, or ERROR

Logs are structured JSON on stderr. Provider credentials and sensitive media fields are redacted. The default in-memory task backend is process-local; a server restart discards active and retained task state.

Keep the runtime database with the queue. MCP task ownership is persisted in runtime.sqlite3 using the fixed tenant_id claim key and principal. Every tasks/get, tasks/update, and tasks/cancel request checks that owner. Missing identity or ownership fails closed in api_key mode. All shared-key members use the same shared-team owner, including after key rotation.

One shared server process gives all of its clients one queue: in local auth mode every loopback client is the same local/local principal, so a job submitted by one client is visible to the others. This remains single-instance state; see transports.md.

Before a required-task handler starts, it atomically records an execution claim in the same database. If that MCP task is delivered again, the handler returns an error without repeating provider work. This favors avoiding duplicate charges over automatic recovery: after an interrupted submission, reconcile its provider outcome before creating a new operation. Optional output-retrieval tasks can be retried because they do not submit paid generation work.

The default in-memory queue still loses task results at process exit. With Redis, retain the runtime database, backend, and encryption key together, and run only one application replica. Snapshot encryption protects caller credentials and HTTP headers stored by FastMCP; Redis must also restrict access to task arguments and results, which may contain media URLs and prompts. rediss:// protects the connection and does not replace snapshot encryption. A wrong or missing key cannot decrypt existing encrypted snapshots. See deployment.md.