Seedance / Seedream MCP

Python MCP server for BytePlus Seedream 5.0 Pro, Seedance 2.0, TOS media staging, and the private portrait asset library. It is designed for local verification first and deployment as a Native Python 3.11 Web Application on BytePlus veFaaS.

Runtime shape

• Streamable HTTP MCP endpoint: POST /mcp

• Health endpoint: GET /health

• Upload widget: GET /widget/

• Upload API: POST /api/uploads

• Redis-backed short-lived sessions

• Per-tenant ModelArk credentials selected from the API Gateway API key

Related MCP server: z_ai_image_gen_mcp

Setup

Create a virtual environment, install dependencies, and copy the environment template:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env

On PowerShell:

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
Copy-Item .env.example .env

Fill every required value in .env. Startup fails immediately when any required value is missing. For generation, configure MCP_TENANTS_JSON and a separate ARK_API_KEY_* secret for each ModelArk project; the legacy shared ARK_API_KEY is never used for generation.

Run locally

bash run.sh

or:

python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Verify:

curl http://127.0.0.1:8000/health
MCP_AUTHORIZATION="<gateway-api-key>" python scripts/smoke_mcp.py http://127.0.0.1:8000/mcp

On Windows, verify the deployed remote MCP and call its runtime-config tool:

.\scripts\test_remote_mcp.ps1

Tools

Planning tools never call generation APIs:

• creative_plan_launch_set

• creative_resolve_video_preset

Deferred in multi-tenant v1:

• media_start_upload_session

• media_finalize_upload_session

• media_get_upload_session

• media_import_generated_asset

Generation:

• seedream_generate_image

• seedance_generate_video

Task control and diagnostics:

• generation_get_task

• generation_list_tasks

• generation_cancel_task

• system_get_runtime_config

• system_validate_byteplus_connectivity

system_get_runtime_config masks all legacy/shared secrets and returns only the calling tenant's principal/project identifiers; it never returns ModelArk keys or other tenants' mappings.

Main workflows

Seedream image

1. Call seedream_generate_image.

2. Reuse the returned reference_session_id directly with Seedance. Outputs generated by ModelArk are trusted and do not need private-asset conversion.

Tenant isolation

The public /mcp endpoint requires the API Gateway key in Authorization. The server hashes that key and maps it to exactly one ModelArk project. The ModelArk key is loaded only from the matching server-side secret and is never returned to the MCP client. Seedance tasks and Seedream reference sessions are owned by that tenant and cannot be reused by another tenant.

Deferred shared-media workflows

The TOS upload, upload widget, and portrait Asset Library workflows are disabled in multi-tenant v1 because their current storage/assets are shared. They will be reintroduced only with isolated project-compatible storage and asset credentials.

Tests

python -m pytest -q

The default suite uses mocks and requires no production credentials. Tests cover config validation, secret masking, schemas, planning helpers, upload state, provider adapters, MCP tool discovery, and MCP initialize.

Live integration calls are intentionally not part of the default suite because they consume provider quota and require configured BytePlus resources.

Claude Desktop local verification

Claude Desktop can reach the Streamable HTTP server through a local bridge:

{
  "mcpServers": {
    "seedance-seedream": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}

Restart Claude Desktop, confirm tool discovery, then try:

1. Create a 2K JPEG product hero image with Seedream.

2. Open the upload flow for a normal image, then animate it with Seedance.

3. Open the portrait upload flow, prepare the private asset, wait until it is Active, then create a five-second 9:16 video.

Expected results are structured tool outputs containing reference session IDs, provider task IDs, asset URIs when active, and suggested next actions.

See DEPLOY.md for veFaaS and API Gateway deployment.