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.
Prerequisites
Section titled “Prerequisites”Complete guided setup or connect to an existing shared server first. Developers preparing the server themselves can use Manual Installation.
Server Overview
Section titled “Server Overview”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.
Background Execution
Section titled “Background Execution”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.
Ordinary-tool workflow (default)
Section titled “Ordinary-tool workflow (default)”- Call
ark_job_capabilitiesto discover targets enabled by server configuration and visible to the current principal. - Call
ark_job_submitwithtool_nameand the exactargumentsobject the original tool accepts. - 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. - Poll
ark_job_getno faster thanpoll_after_msuntilstatusis terminal. - Read the original MCP tool result from
result. For provider-submission tools, itsstructured_contentcontains the provider task ID. - Use
ark_job_cancelfor 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.
Native task workflow
Section titled “Native task workflow”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.
Seedream Review And Edit
Section titled “Seedream Review And Edit”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.
- Discover the model and dry-run the intended request. Record an explicit
paid-attempt limit and USD estimate budget covering generation, any
seed_understandreviews and edits.preview.price_sourceiscatalogorbuiltin, not an actual charge. Stop when either limit is reached. - Submit once through
ark_job_submit. Keep the Ark job ID and completed per-callrequest_id, submittedseed, finalprompt_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. - Check
item_errorsor variation errors, persistence and byteinspection. A delivered PNG is not automatically a passing image. Inspection problems do not cause paid rerolls. - Review the immutable output visually, using an authorized human or
seed_understandthrough an ordinary job. Export/read a durable image or upload it withmedia_uploadfor 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. - Record
Pass,Partial,Fail, orNot evaluatedwith evidence. A reviewer refusal or unavailable review isNot evaluated, not a generation failure; exclude it from assessed pass-rate denominators and do not bypass refusals. - For an authorized correction, call
seedream_generate_imagewith the source inimages, a focused edit instruction and optional structuredpoint/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. - 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.
Opt-In Seedream Smoke Matrix
Section titled “Opt-In Seedream Smoke Matrix”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.
Python Task Workflow
Section titled “Python Task Workflow”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 asyncioimport jsonimport osimport sysfrom pathlib import Path
from fastmcp import Clientfrom fastmcp.client.transports import StdioTransportfrom 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.
Providing Credentials
Section titled “Providing Credentials”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.
Claude Desktop
Section titled “Claude Desktop”Use the Claude Desktop guide. A separate coding agent can prepare local setup; Desktop then starts Ark automatically.
Cursor IDE
Section titled “Cursor IDE”Use the Cursor guide. Prefer guided setup and check actual discovery results, not just a connection indicator.
VS Code (MCP Extension)
Section titled “VS Code (MCP Extension)”Use the VS Code guide. It distinguishes the
profile/workspace servers format from portable Copilot configuration.
MCP Inspector
Section titled “MCP Inspector”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:
make inspectThis 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.
Troubleshooting
Section titled “Troubleshooting”SSL Certificate Errors (macOS)
Section titled “SSL Certificate Errors (macOS)”If you see CERTIFICATE_VERIFY_FAILED, confirm truststore is installed and
start through python -m ark_mcp so the complete entrypoint runs.
“API key not configured” Error
Section titled ““API key not configured” Error”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.
Server Not Discovered by Client
Section titled “Server Not Discovered by Client”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.
Tools Missing
Section titled “Tools Missing”If only some products’ tools are registered:
- No ModelArk key → no
seedream_generate_image,seedance_create_task,gen_task_*,seed_understand, orseed_audio_understand - No Seed Speech key → no
seed_audio_generateorspeech_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.
Environment Variables Reference
Section titled “Environment Variables Reference”| 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.