Skip to content

Client Integrations

Choose the client you want to use. You configure the connection once; the client starts Ark automatically. You do not need to run the launch command yourself whenever you open a chat.

Client Easiest starting point
Claude Desktop Have a coding agent prepare its configuration, then enable it in Desktop
Claude Code Ask Claude Code to perform guided setup
Codex Ask a terminal-enabled Codex session to perform guided setup
TRAE Ask its coding agent to prepare setup; confirm any MCP settings UI steps
Cursor Use a file/terminal-enabled agent for guided setup
VS Code Use an enabled coding agent, then review the MCP connection
OpenCode Ask OpenCode to perform guided setup for its installed version
Python Developer example for building your own client

Use the guided setup request before opening manual configuration snippets. It requires terminal and file-editing access; ordinary chat alone cannot install software. For a team-provided endpoint, connect over HTTPS instead.

Default to user-level registration so Ark is available across projects. Choose project-only scope when you need it. Your agent should preserve other MCP entries and ask before replacing an existing connection.

Your setup agent resolves the executable, checkout and private credential-file paths, installs the reviewed locked environment, and prepares the correct client entry. You only need to approve changes, enter keys privately and complete any required UI confirmation.

The fallback snippets in each client guide are for manual setup or troubleshooting, not additional steps after guided setup. Their prerequisites and exact launch contract are in Manual Installation. Do not paste unresolved placeholder paths into a client.

Enter only the keys you need in a private local text editor. The file stays outside your repository and shared folders; client configuration contains its path, not key values. Preserve existing credentials. Never paste populated configuration, raw logs or validation errors into chat.

After saving the entry, review the client’s server trust prompt and enable ark-seed. Check active jobs before reloading or restarting a client.

Use this request in the client:

Use only the ark-seed server. List its tools, call ark_list_models with
{"input": {}}, and call ark_job_capabilities with {}. Report enabled
services, exact model IDs, model limits, and available job targets.
Do not generate, understand, transcribe, upload, or submit any jobs.

ark_list_models and ark_job_capabilities are read-only and make no provider calls. The former describes configured models and services; the latter returns enabled job targets and their actual input schemas. A connected server with empty models/targets may simply have no provider credentials loaded. Discovery proves configuration and tool availability, not API-key validity, account entitlement, or model whitelist access.

The setup agent’s isolated preflight procedure is in Manual Installation. There is no need for users to run a separate validation script.

Ask your client to use Ark’s ordinary background-job tools and report the result when ready. It handles submission and polling; you do not need to copy job JSON manually. For an optional no-charge check, use the request preview.

Keep the connection open while work runs. Restarting loses default in-memory jobs, and another local client cannot poll them. Never repeat a generation just to check progress. Technical result handling is in Background Execution.

  • Server does not start: check the resolved executable, checkout, completed locked sync, JSON/TOML syntax, and selected execution host.
  • Connected but expected tools are missing: check private env-file metadata, enabled services, feature flags, and inherited-variable shadowing. Never request the populated env file or raw validation exceptions in chat.
  • A job ID is unavailable: ensure you are polling the same process and that it has not restarted or expired the result.
  • Edition rejects the configuration: use that client’s guide and official source. Do not swap envelope keys blindly or inline keys as a workaround.

Official client references are listed in each sibling guide. The shared launch contract follows the current server configuration. These protocol/runtime references were consulted on 2026-11-10: