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.
Runtime upgrade
Section titled “Runtime upgrade”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.
make start# equivalentuv run python -m ark_mcpUse 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.
Streamable HTTP
Section titled “Streamable HTTP”Loopback development can use local auth:
MCP_TRANSPORT=http MCP_HOST=127.0.0.1 uv run python -m ark_mcpShared 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:
make shared-http# equivalentMCP_AUTH_MODE=local MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=3000 uv run python -m ark_mcpAll 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_DIRso the state database does not depend on the server’s working directory.
Protected network deployment
Section titled “Protected network deployment”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:
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_mcpThe 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.
Operational HTTP routes
Section titled “Operational HTTP routes”| 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.
MCP Inspector
Section titled “MCP Inspector”make inspect# or with reloadmake inspect-devFor authenticated HTTP inspection, configure the inspector/client privately with the shared MCP bearer key. Its ordinary scopes are fixed by the server.