Skip to content

Integration Guide

This is the technical reference for background execution. For everyday setup, start with Set Up Ark MCP and your client guide. Users can ask their client in plain language; the client handles tool calls.

Complete guided setup or connect to an existing shared server first. Developers preparing the server themselves can use Manual Installation.

The server runs as a stdio process — the MCP client spawns it as a subprocess and communicates over stdin/stdout. The entry point is python -m ark_mcp, which injects truststore for macOS TLS certificate verification before starting the FastMCP server.

Use python -m ark_mcp in client configurations so transport security settings are applied consistently. The server module also injects truststore before provider clients are created.

Long-running work stays asynchronous for every client. The server exposes two entry paths to the same FastMCP Docket worker:

Entry path Client requirement Result retrieval
ark_job_submit with the original tool name and arguments (default) Any MCP client (no task extension needed) ark_job_get
Call the original tool with task augmentation MCP 2026-07-28 task extension tasks/get

Use the ordinary ark_job_* tools by default. MCP tasks remain experimental and most clients cannot negotiate task augmentation; verify against the client release in front of you rather than assuming support. The ordinary path needs no task-specific transport feature, runs the selected tool in the same background worker, and preserves the original tool result inside result.structured_content when the job completes.

A client that does negotiate the task extension may call the original tools with task metadata instead; that path is fully supported and unchanged. A foreground call made directly to a required-task tool is still rejected before provider submission.

The repository tests both paths with the locked FastMCP 4.1.8 runtime. The ordinary path is covered in-process, over a real subprocess stdio transport, and over authenticated Streamable HTTP without advertising the task extension. These tests use mocked providers and do not make billable generation calls. Exact desktop/IDE releases and their automatic tool-selection behavior can change; the standard ark_job_* protocol surface is the portable contract.

  1. Call ark_job_capabilities to discover targets enabled by server configuration and visible to the current principal.
  2. Call ark_job_submit with tool_name and the exact arguments object the original tool accepts.
  3. Store the returned Ark job_id. Do not confuse it with a Seedance, Seed 3D, or VOD provider task ID returned later by the original tool.
  4. Poll ark_job_get no faster than poll_after_ms until status is terminal.
  5. Read the original MCP tool result from result. For provider-submission tools, its structured_content contains the provider task ID.
  6. Use ark_job_cancel for a locally running job when needed. Cancellation is cooperative and does not guarantee cancellation of provider work already accepted upstream.

Inspect terminal status and result.is_error before using result.structured_content; completion alone is not success. The Python client guide has a complete discovery and dry-run example with bounded polling and error checks. The first-run guide provides copyable generation prompts and optional no-charge checks.

A client that negotiates the task extension can call the same tools with task augmentation instead; that path follows the official FastMCP task documentation. The example under Python Task Workflow uses it.

Generation delivery and visual acceptance are separate outcomes. This workflow uses existing tools; the Ark MCP integration exposes no native OCR or layer decomposition, even when the provider API supports those operations.

  1. Discover the model and dry-run the intended request. Record an explicit paid-attempt limit and USD estimate budget covering generation, any seed_understand reviews and edits. preview.price_source is catalog or builtin, not an actual charge. Stop when either limit is reached.
  2. Submit once through ark_job_submit. Keep the Ark job ID and completed per-call request_id, submitted seed, final prompt_sha256, request_options, usage, artifact ID and artifact SHA-256. Store the original prompt and reference hashes in a private manifest; the hash is not the prompt.
  3. Check item_errors or variation errors, persistence and byte inspection. A delivered PNG is not automatically a passing image. Inspection problems do not cause paid rerolls.
  4. Review the immutable output visually, using an authorized human or seed_understand through an ordinary job. Export/read a durable image or upload it with media_upload for a provider-readable reference. Evaluate exact spelling/case, forbidden text (including absence checks), object/person counts, geometry, visibility, anatomy and composition against the brief. An understanding response is fallible evidence, not authoritative OCR.
  5. Record Pass, Partial, Fail, or Not evaluated with evidence. A reviewer refusal or unavailable review is Not evaluated, not a generation failure; exclude it from assessed pass-rate denominators and do not bypass refusals.
  6. For an authorized correction, call seedream_generate_image with the source in images, a focused edit instruction and optional structured point/bbox. Preserve the original; record parent artifact/hash, edit instruction, submitted markup hash, new request/artifact IDs and review as a new paid attempt. A fixed seed helps reproduce request settings but does not guarantee identical pixels or successful text/count/geometry.
  7. Select an output only after acceptance. Verify inline image previews after publishing to a sheet or document; publishing/link repair belongs to the consumer integration, not the Seedream adapter.

Never resubmit after an ambiguous timeout simply to get another answer. Resume the existing job or reconcile its request ID first. Recovery of persisted media is distinct from another paid generation.

uv run python scripts/smoke_seedream55.py prints offline help and makes no provider calls. Live execution requires both --execute and --confirm-cost <positive USD estimate limit>, configured local ModelArk credentials and an exact configured 5.5 model (use --model if Pro is the default). The script dry-runs every selected case and prints the aggregate estimate before submitting any billable generation. A rejected/ambiguous call stops the matrix; submissions are never retried.

Default cases cover opaque JPEG, transparent PNG, reference edit, point edit and bbox edit, using synthetic local PNG references rather than paid setup images. --case selects a subset; --max-cases caps the count. Optional Pro compatibility requires an explicit --pro-model and sufficient case cap (--max-cases 6 for the complete matrix). Results go to a fresh private run directory under .artifacts by default, with sanitized report.json and durable media.

The script checks persistence, hashes, decode, dimensions, format and visible alpha. A byte-smoke pass does not prove the requested color change or region adherence: visually review editing semantics and composition separately. Polling is bounded; a timeout is not permission to rerun an accepted job.

This optional developer example is not needed for setup. Run it in the reviewed environment with ARK_MCP_ENV_FILE pointing to your private file and SMOKE_REFERENCE_IMAGE_URL pointing to an accessible reference image. This example submits one billable video generation. The provider ID is saved before polling; if polling fails, use that ID to resume retrieval rather than repeating submission. The MCP task ID identifies the worker operation, while the provider ID identifies the video generation.

Native-task Python example (billable)
import asyncio
import json
import os
import sys
from pathlib import Path
from fastmcp import Client
from fastmcp.client.transports import StdioTransport
from fastmcp_tasks import call_tool_task
async def main():
transport = StdioTransport(
command=sys.executable,
args=["-m", "ark_mcp"],
env={
"ARK_MCP_ENV_FILE": os.environ["ARK_MCP_ENV_FILE"],
"MCP_TRANSPORT": "stdio",
"MCP_AUTH_MODE": "local",
},
keep_alive=False,
)
async with Client(transport) as client:
submission = await call_tool_task(
client,
"seedance_create_task",
{"input": {
"prompt": "A gentle camera move through the scene",
"images": [{
"kind": "url",
"url": os.environ["SMOKE_REFERENCE_IMAGE_URL"],
"role": "reference_image",
}],
"duration": 5,
"resolution": "480p",
}},
)
print("MCP submission task:", submission.task_id)
created = await submission.result()
provider_id = created.structured_content["tasks"][0]["task_id"]
directory = Path(".artifacts")
directory.mkdir(exist_ok=True)
with (directory / "provider_tasks.jsonl").open("a") as stream:
stream.write(json.dumps({"task_id": provider_id}) + "\n")
stream.flush()
os.fsync(stream.fileno())
for _ in range(30):
status = await client.call_tool(
"gen_task_get",
{"input": {"task_ids": [provider_id], "persist_output": False}},
)
result = status.structured_content
if result["errors"]:
raise RuntimeError(f"Provider task {provider_id}: {result['errors'][0]}")
state = result["tasks"][0]["status"]
if state == "succeeded":
break
if state in {"failed", "cancelled", "expired"}:
raise RuntimeError(f"Provider task {provider_id}: {state}")
await asyncio.sleep(result["recommended_poll_after_ms"] / 1000)
else:
raise TimeoutError(f"Resume polling provider task {provider_id}")
persistence = await call_tool_task(
client,
"gen_task_get",
{"input": {"task_ids": [provider_id], "persist_output": True}},
)
completed = await persistence.result()
print(completed.structured_content["tasks"][0]["outputs"])
asyncio.run(main())

task.result() waits through tasks/get and returns the terminal tool result. In this single-process stdio example, FastMCP 4.1.8 automatically task-augments client.call_tool() for the optional status tool as well; persist_output=false still prevents downloads. The standalone smoke scripts use modern and public mode="legacy" clients connected to the same in-process server lifespan to exercise a genuinely foreground status call. Do not launch a second stdio server against the same SQLite state to obtain that behavior. A provider success can still have video=null when best-effort persistence fails; inspect the result before treating the artifact as delivered. The same submit/status/persistence sequence is tested offline by the smoke-workflow tests; tests/e2e/test_stdio_tasks.py separately verifies a real subprocess task result.

Use a private file outside the repository, referenced by ARK_MCP_ENV_FILE. Enter keys locally, never in chat, client JSON or shared configuration. Guided setup prepares that file; Provider Keys explains which fields you need. Inherited environment variables can override the file, so investigate shadowing without displaying values.

Use the Claude Desktop guide. A separate coding agent can prepare local setup; Desktop then starts Ark automatically.

Use the Cursor guide. Prefer guided setup and check actual discovery results, not just a connection indicator.

Use the VS Code guide. It distinguishes the profile/workspace servers format from portable Copilot configuration.

The MCP Inspector is an optional developer tool, not a setup requirement. The ordinary connection check runs inside your AI client.

Developer Inspector launch

From an already prepared checkout, with the private env-file path configured:

Terminal window
make inspect

This launches fastmcp inspect src/ark_mcp/server.py:mcp; the server module injects truststore before provider clients are created.

For HTTP inspection, use an existing protected server and your authorized connection credentials. Never export provider keys into shell history or disable authentication to connect.

If you see CERTIFICATE_VERIFY_FAILED, confirm truststore is installed and start through python -m ark_mcp so the complete entrypoint runs.

Check the private ARK_MCP_ENV_FILE path, requested credential names and feature flags, then reconnect after finishing active jobs. Do not print the file or raw settings-validation exceptions. See missing tools.

Have the setup agent check the resolved executable, checkout, locked environment and any unfinished UI approvals. It should inspect private diagnostics locally, not dump complete logs into chat. See Manual Installation.

If only some products’ tools are registered:

  • No ModelArk key → no seedream_generate_image, seedance_create_task, gen_task_*, seed_understand, or seed_audio_understand
  • No Seed Speech key → no seed_audio_generate or speech_to_text
  • Optional products (Seed 3D, OmniHuman, VOD MediaKit, object storage, asset library) also need their own keys or feature flags; see Configuration.

ark_list_models reports which optional services are enabled.

Variable Required Default Description
BYTEPLUS_MODELARK_API_KEY For image/video — ModelArk Bearer auth key
BYTEPLUS_SEED_SPEECH_API_KEY For audio — Seed Speech X-Api-Key
BYTEPLUS_MODELARK_BASE_URL No https://ark.ap-southeast.bytepluses.com/api/v3 ModelArk region endpoint
BYTEPLUS_SEED_AUDIO_BASE_URL No https://voice.ap-southeast-1.bytepluses.com Seed Speech endpoint
SEEDREAM_DEFAULT_MODEL No dola-seedream-5-5-261028 Seedream 5.5 model ID; retain an explicit 5.0 Pro default if not authorized
SEEDANCE_DEFAULT_MODEL No dreamina-seedance-2-5-260628 Default Seedance model ID for seedance_create_task (Seedance 2.5)
MCP_TRANSPORT No stdio stdio or http
MCP_HOST No 127.0.0.1 HTTP bind address
MCP_PORT No 3000 HTTP port
MCP_AUTH_MODE No local Set api_key for non-loopback HTTP; Docker, Compose and Terraform already default to api_key
MCP_API_KEY_SHA256 For api_key — Lowercase SHA-256 digest of the shared MCP key; never the raw key
MCP_ALLOWED_HOSTS For HTTP loopback Accepted Host headers
MCP_ALLOWED_ORIGINS For browser HTTP — Accepted browser origins
ARTIFACT_DIR No .artifacts Local artifact storage
ARTIFACT_TTL_SECONDS No 604800 (7 days) Artifact retention

Clients send the shared MCP key in a private bearer header; provider keys stay on the server. Every member uses tenant/principal shared-team with fixed ordinary scopes, shared ownership and one budget. Asset and moderation administration is excluded. For key generation, rotation and migration without automatic ownership transfer, see Self-Hosting.

See Configuration for model bindings, body limits, concurrency, and budget settings.