Deployment
Remote deployment uses FastMCP Streamable HTTP with fail-closed shared MCP key authentication. Local stdio remains the simplest operating mode.
For a single-organization deployment, see Self-Hosting and the Docker Compose kit. The kit includes TLS ingress, an authenticated internal Redis job backend, and hardened application settings. Its guide identifies remaining live-deployment checks.
For BytePlus infrastructure, use the Terraform starter and operator guide. It provisions one ECS host, a retained state disk, HTTPS networking, and optional private TOS storage. Disk mounting and private credential activation are explicit operator steps; a successful infrastructure apply is not application readiness.
For a published build, use a versioned ghcr.io/byteplus-sa/ark-mcp:vX.Y.Z
image or pin the digest from its GitHub Release. The registry’s latest
tracks releases, while edge tracks passing main builds. See
Versioning and releases for artifacts, approval, and rollback.
Build the container
Section titled “Build the container”docker build --tag ark-mcp:latest .The image uses pinned Python and uv versions, installs the locked production
environment, runs as UID/GID 1001, and probes /health with Python’s standard
library. Docker, Compose and Terraform default to MCP_AUTH_MODE=api_key;
supply MCP_API_KEY_SHA256 through protected runtime configuration. Python
settings default to local for stdio or loopback HTTP only. Use a build
containing shared-key support; older images reject this mode. Upgrading a
former JWT deployment requires the
breaking-change migration.
Run one protected instance
Section titled “Run one protected instance”Generate the key with scripts/generate_mcp_key.py and load the emitted digest
into the operator’s environment privately. The server receives only the hash;
the raw key belongs in each member’s private client bearer-header configuration.
docker run --detach \ --name ark-mcp \ --publish 127.0.0.1:3000:3000 \ --env BYTEPLUS_MODELARK_API_KEY \ --env BYTEPLUS_SEED_SPEECH_API_KEY \ --env MCP_AUTH_MODE=api_key \ --env MCP_API_KEY_SHA256 \ --env MCP_ALLOWED_HOSTS=mcp.example.com,127.0.0.1 \ --env MCP_ALLOWED_ORIGINS=https://client.example.com \ --volume ark-mcp-artifacts:/app/.artifacts \ ark-mcp:latestPlace a TLS-terminating reverse proxy in front of the loopback-published port.
Disable proxy buffering for Streamable HTTP/SSE and set read/send timeouts at
least as high as BYTEPLUS_REQUEST_TIMEOUT_MS. Preserve the public Host header
so the server allowlist can validate it.
Probes and monitoring
Section titled “Probes and monitoring”curl --fail http://127.0.0.1:3000/healthcurl --fail http://127.0.0.1:3000/readycurl --fail http://127.0.0.1:3000/metrics/healthreports process liveness without contacting providers./readychecks the runtime-owned SQLite state, artifact directory, and (whenREADINESS_CHECK_PROVIDERS=true) provider connectivity./metricsexports tool/provider request counts, duration, retries, artifact writes, and budget rejections for Prometheus.
Provider calls also create FastMCP/OpenTelemetry child spans when tracing is configured. Application logs are structured JSON on stderr and redact secrets.
Kubernetes shape
Section titled “Kubernetes shape”Use one replica with a persistent volume until distributed state adapters are implemented. The important container settings are:
containers: - name: ark-mcp image: ark-mcp:latest ports: - name: http containerPort: 3000 env: - {name: MCP_TRANSPORT, value: http} - {name: MCP_HOST, value: 0.0.0.0} - {name: MCP_AUTH_MODE, value: api_key} - name: MCP_API_KEY_SHA256 valueFrom: secretKeyRef: name: ark-mcp-auth key: mcp-api-key-sha256 - {name: MCP_ALLOWED_HOSTS, value: mcp.example.com} - {name: MCP_ALLOWED_ORIGINS, value: "https://client.example.com"} readinessProbe: httpGet: {path: /ready, port: http} livenessProbe: httpGet: {path: /health, port: http} securityContext: allowPrivilegeEscalation: false readOnlyRootFilesystem: true runAsNonRoot: true runAsUser: 1001 volumeMounts: - {name: artifacts, mountPath: /app/.artifacts}Mount /app/.artifacts writable even with a read-only root filesystem. Load
provider credentials from a Secret rather than literal manifest values.
State, artifacts, and shutdown
Section titled “State, artifacts, and shutdown”- HTTP is stateless.
python -m ark_mcpserves Streamable HTTP withstateless_http=True(__main__.py); long-running work is tracked by job IDs, not MCP sessions (see SPEC_BACKGROUND_JOBS.md). - Shutdown waits for in-flight requests up to
BYTEPLUS_REQUEST_TIMEOUT_MS(uvicorntimeout_graceful_shutdown). Set the orchestrator’s termination grace period at least that long. - SQLite is the only state backend.
STATE_BACKEND=sqliteis the only accepted value, and startup logssingle_instance_state_backendas a reminder to run one replica (runtime.py::build_state_stores). - Artifacts can live off the pod.
ARTIFACT_BACKEND=object_storagestores durable artifacts in the configured TOS or S3 bucket; startup fails withoutTOS_*orS3_*credentials. The sweeper does not delete objects there, so configure a bucket lifecycle rule that matchesARTIFACT_TTL_SECONDS. - A background sweeper runs every
ARTIFACT_SWEEP_INTERVAL_SECONDS(default3600). It deletes expired filesystem artifacts and cache rows, and prunes ownership, object-key and budget rows older thanSTATE_PRUNE_MAX_AGE_DAYS(default30).
Security checklist
Section titled “Security checklist”- Use HTTPS and
api_keymode for every non-loopback bind. - Store only the MCP key’s hash on the server; distribute the raw key privately.
- Treat all members as one
shared-teamowner with a shared budget and fixed ordinary scopes. Account-wide asset and moderation administration is denied. - Set explicit Host and Origin allowlists.
- Set
RATE_LIMIT_RPMto cap per-client-IP request frequency when exposed to untrusted clients. Behind a reverse proxy, setRATE_LIMIT_TRUST_PROXY_HEADERS=trueonly if the proxy overwritesX-Forwarded-For; otherwise every client shares the proxy’s bucket. - Keep the HTTP body limit and provider URL SSRF checks enabled.
- Mount the artifact directory with least privilege and protect backups.
- Restrict operational endpoints at the proxy/network layer as appropriate.
- Run one replica; filesystem/SQLite state and in-process limiters are not a distributed coordination mechanism.
- Keep
uv.lock, base images, and GitHub Actions pins current through review.
See Configuration, Transports, and Troubleshooting for the complete operating contract.
Background tasks in a single-replica deployment
Section titled “Background tasks in a single-replica deployment”Redis retention does not enable multiple replicas. Provider budgets,
ownership, execution claims, artifact state and concurrency controls still use
single-instance services. Keep runtime.sqlite3 on durable storage when using
FASTMCP_DOCKET_URL=redis://... or rediss://..., and preserve it with the queue.
API-key-authenticated Redis task deployments must set
FASTMCP_TASKS_ENCRYPTION_KEY through the secret manager. Startup rejects an
unencrypted backend. Use at least 32 random characters, the same key for all
retained snapshots, TLS for the connection, and restricted Redis access.
Snapshots carry caller credentials; task arguments/results may also contain
sensitive media and require backend-level protection.
After worker loss, an already-started required task fails on redelivery instead of replaying paid provider work. Reconcile the saved provider ID where available; if the submission result was lost, investigate provider-side status before creating another operation. Optional output-retrieval tasks remain repeatable. Deleting the runtime database or retaining queue state beyond execution-history retention invalidates this recovery contract. No automatic exactly-once provider submission guarantee is made.
Offline regression coverage includes encrypted snapshot round trips, wrong-key failure, and a simulated interrupted provider operation across a reopened runtime database. Live Redis failover and named desktop-client task support require validation in the target environment; the supported protocol test uses FastMCP 4.1.8 over a real stdio subprocess with a mocked provider.
Single shared loopback server (local multi-client)
Section titled “Single shared loopback server (local multi-client)”When several local MCP clients must share background jobs, run one loopback
server in local auth mode instead of one stdio process per client:
make shared-httpEvery loopback client is the same local/local principal and shares the
in-process Docket queue and runtime.sqlite3, so any client can poll a job
submitted by another. This does not change the single-replica contract: the
in-memory queue is lost on restart, budgets/ownership/execution claims remain
SQLite-backed, and Redis retention stays single-replica. See
transports.md for the client configuration and caveats.