Skip to content

Transports

The server supports stdio and FastMCP Streamable HTTP.

Connecting as a user? Use guided local setup or an existing shared server. The commands on this page are for developers and server operators, not extra steps after adding Ark to your client.

The locked runtime is FastMCP 4.1.8, which includes the authorization fixes released in 4.1.2. Compared with 4.0, stateful HTTP sessions inherit the MCP SDK’s 30-minute idle timeout; clients must reconnect expired sessions. Drain active generation jobs before restarting for an upgrade, especially with the default in-memory queue. See the 4.1 upgrade notes.

stdio is the secure local default. MCP JSON-RPC uses stdin/stdout; structured logs use stderr.

Terminal window
make start
# equivalent
uv run python -m ark_mcp

Use this mode when an MCP client launches the server as a subprocess. The local principal owns artifacts and Seedance tasks created by that process. The client runs the saved command automatically. Starting a separate terminal process does not connect that process to your client’s stdio session.

Loopback development can use local auth:

Terminal window
MCP_TRANSPORT=http MCP_HOST=127.0.0.1 uv run python -m ark_mcp

Shared loopback server for multiple local clients

Section titled “Shared loopback server for multiple local clients”

stdio starts one server process per client, and background job state lives in that process. To let several local MCP clients — for example multiple opencode agents — submit and poll the same ark_job_* jobs, run one shared loopback server in local auth mode and point every client at it:

Terminal window
make shared-http
# equivalent
MCP_AUTH_MODE=local MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=3000 uv run python -m ark_mcp

All loopback clients resolve to the same local/local principal, share the single in-process Docket queue, and share the runtime.sqlite3 ownership store, so any client can poll a job submitted by any other client. An opencode remote client entry looks like:

{
"mcp": {
"ark-mcp": {
"type": "remote",
"url": "http://127.0.0.1:3000/mcp",
"oauth": false,
"timeout": 600000
}
}
}

Caveats:

  • The default in-memory Docket backend is process-local: restarting the shared server discards active and retained jobs. Set FASTMCP_DOCKET_URL=redis://... to retain task state across restarts of the same single-replica deployment; the server’s embedded worker picks retained tasks back up. A separate worker process is only needed for extra task parallelism.
  • Keep RATE_LIMIT_RPM=0 (the default): every loopback client shares one client-IP bucket, so enabling it applies an aggregate cap.
  • Set an absolute ARTIFACT_DIR so the state database does not depend on the server’s working directory.

Network deployment uses only shared-key authentication. Generate the key with scripts/generate_mcp_key.py and store its emitted MCP_API_KEY_SHA256 assignment in private server configuration before starting:

Terminal window
MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
MCP_AUTH_MODE=api_key \
MCP_ALLOWED_HOSTS=mcp.example.com \
MCP_ALLOWED_ORIGINS=https://client.example.com \
uv run python -m ark_mcp

The server hashes each bearer key and compares it with the configured digest. Host/Origin protection and a streamed body-size limit are enabled. Terminate TLS at a trusted reverse proxy and pass the original Host header.

Clients send Authorization: Bearer <shared MCP key> over HTTPS. There is no login or OAuth discovery. All members use tenant and principal shared-team, sharing data, budgets and fixed ordinary scopes; asset and moderation administration is excluded. Local file operations remain unavailable. Docker, Compose and Terraform default to api_key; Python defaults to local. For retired authentication settings, see breaking-change migration.

Route Authentication Meaning
/health none Process liveness
/ready none Runtime, database, and artifact-directory readiness. When READINESS_CHECK_PROVIDERS=true, also checks provider connectivity and includes a providers field; returns 503 "degraded" if any provider is unreachable
/metrics none Prometheus exposition

Restrict /metrics at the network or reverse-proxy layer if metric labels or traffic volumes are operationally sensitive. MCP traffic remains on FastMCP’s configured Streamable HTTP path.

Terminal window
make inspect
# or with reload
make inspect-dev

For authenticated HTTP inspection, configure the inspector/client privately with the shared MCP bearer key. Its ordinary scopes are fixed by the server.