MCP server and generic dispatch

The Model Context Protocol, MCP, is a standard way for an AI assistant to call external tools. clika-cli mcp turns the CLI into an MCP server, so an assistant such as Claude Code or Cursor can read your devices, launch a benchmark and fetch its results by calling tools rather than by shelling out.

tools and call are the same machinery exposed to you directly. tools lists every operation by its tool name, and call invokes one. They are useful for scripting, for reaching an endpoint that has no convenient subcommand, and for reproducing by hand exactly what an assistant did.

Connecting Claude Desktop, Claude Code, Codex or another client end to end is covered in Using with AI (MCP). This page documents the commands and their flags.

mcp

clika-cli mcp [flags]

Runs an MCP server on standard input and output. You do not run this at a terminal yourself. You configure an AI harness to launch it, and the harness speaks the protocol over the pipe.

Every documented platform operation is a tool with a JSON schema, except the platform administration API (/api/admin/**), which no toolset serves. By default the server lists the api-key toolset, the operations an API key can be granted. --toolset full lists every operation (see Toolsets).

Flag	Type	Default	Meaning
--toolset	string	api-key	Which named toolset to serve.
--remote	bool	false	Proxy to the orchestrator's own HTTP MCP endpoint instead of dispatching from the embedded API description.
--skip-update-check	bool	false	Do not check the deployment's release channel for a newer CLI at start.

The global flags all apply, and the ones that matter here are --profile, --token, --api-key, --base-url and --insecure-tls, because the server authenticates to the platform exactly as any other command does.

clika-cli mcp
clika-cli mcp --toolset full
clika-cli mcp --toolset device-ops
clika-cli mcp --profile onprem --insecure-tls
clika-cli mcp --remote --profile onprem --insecure-tls

Toolsets

A toolset is a named selection of the platform's tools for one kind of work.

Toolset	What it covers
api-key (default)	The operations an API key can be granted. Sign-in flows, the capabilities only a browser session can hold (users, roles, SSO, license and billing changes) and multipart-only uploads are in full only.
full	Every documented operation except the platform administration API.
device-ops	Day-to-day device work: list and inspect devices, read health, run commands, push and fetch files, browse artifacts.
benchmark-ops	Benchmark runs end to end: the type catalog, the model pool, the compatibility check, picking registered or hosted targets, launching a group, polling it, reading results. Also the ClikaRT archive listing and download link, so an assistant can fetch the runtime the run used (Download the ClikaRT SDK).

Ask a deployment what it serves:

$ curl -H "Authorization: Bearer clika_..." https://platform.clika.io/api/mcp/toolsets

A toolset is only offered where the product's API covers all of it, and an unknown or unavailable name fails with the servable names listed. In local mode the server also reads the credential's own capabilities from the platform at start and lists only the tools that credential can call, and says on standard error how many of the toolset's tools it serves.

A toolset is not a permission boundary. It changes only which tools are listed. Every call still passes the platform's full authentication, licensing and permission checks, and a client that already knows a tool name can call it through the full endpoint. To restrict what a credential may do, scope the API key instead. See authentication.

Local mode versus --remote

By default the CLI answers from its own embedded copy of the API description, and dispatches each call as an HTTP request to the platform. That works everywhere, including against a self-signed on-premise deployment, because the CLI terminates TLS itself and --insecure-tls is scoped to its own connections.

With --remote, the CLI instead proxies to the orchestrator's Streamable HTTP MCP endpoint at /api/mcp, fetching the tool list from the server when it connects. Two consequences:

• The tool surface follows the server. A platform that gains an operation exposes it immediately, with no CLI update.
• --insecure-tls is scoped to one connection. This is the reason --remote exists. An MCP host that cannot be told to trust a self-signed certificate can point at the local CLI instead, and the CLI makes the one connection that needs the exception. The blunt alternative, disabling certificate verification for the host's entire process, is worth avoiding.

--toolset composes with --remote, selecting the server's /api/mcp/<toolset> endpoint.

Connecting without the CLI at all

Each orchestrator serves the same tools directly over Streamable HTTP at POST /api/mcp, built from its own copy of the API description. A tool call is dispatched in-process back through the API router, so it passes the same authentication, licensing and permission checks a direct API request would. The endpoint is stateless, and a request without a valid credential is rejected before the MCP handler runs.

Point any HTTP MCP client at it with a session token or a clika_ API key in the Authorization header. Where the deployment uses a self-signed certificate, the client, not the CLI, is the one that has to trust the certificate authority, which is exactly the case mcp --remote exists to rescue.

mcp install, uninstall, status and headers

clika-cli mcp install <client> [flags]
clika-cli mcp uninstall <client> [flags]
clika-cli mcp status

mcp install registers the platform's MCP server with an AI client by writing an entry into the client's own config file, so nobody edits JSON or TOML by hand. <client> is claude-code, claude-desktop or codex. mcp uninstall removes what install added, and mcp status reports, for each client, whether the server is registered, under which name and profile, which config file was read and why that file. Neither claude nor codex is run. The CLI edits the file directly.

Flag	Commands	Type	Default	Meaning
--name	install	string	clika-platform	The name of a new entry. An entry this profile installed earlier keeps its name.
--config-path	install, uninstall	string	none	The client's config file, instead of the detected one.
--dry-run	install, uninstall	bool	false	Print the change and write nothing.

The global flags that matter here are --profile, whose key the entry uses, --base-url, which must match the profile's deployment, and --insecure-tls, which changes the entry's shape (below). A profile does not record --insecure-tls, so pass it to install whenever the deployment needs it.

clika-cli mcp install claude-code
clika-cli mcp install claude-desktop --profile onprem --insecure-tls
clika-cli mcp install claude-code --name clika-staging --profile staging
clika-cli mcp install codex
clika-cli mcp install claude-code --dry-run
clika-cli mcp status
clika-cli mcp uninstall claude-code

The login check

Before writing anything, install checks the profile's API key with one request to the deployment (GET /api/auth/capabilities). It stops when the profile has no saved key, when it belongs to a different deployment than --base-url, or when the deployment answers 401. At a terminal it then offers to run the login and continues once the new key is accepted. Without a terminal it prints the exact login command to run. A certificate error ends the check with a hint to pass --insecure-tls. Nothing is written until the key works.

What each client gets

Client	Config file	Entry
claude-code	The user-scope mcpServers of ~/.claude.json, or $CLAUDE_CONFIG_DIR/.claude.json when that is set.	HTTP to <base-url>/api/mcp, with its Authorization header from headersHelper. With --insecure-tls, a stdio entry running mcp --remote.
claude-desktop	claude_desktop_config.json, in ~/Library/Application Support/Claude/ on macOS and $XDG_CONFIG_HOME/Claude/ or ~/.config/Claude/ on Linux. On Windows, %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\ for the Microsoft Store install, found by asking Windows which Claude_* package is installed for your user, and %APPDATA%\Claude\ otherwise.	A stdio entry running mcp --remote.
codex	[mcp_servers.<name>] in ~/.codex/config.toml, or $CODEX_HOME/config.toml when that is set (%USERPROFILE%\.codex\ on Windows). The Codex CLI, its IDE extension and ChatGPT Desktop all read this file.	HTTP to <base-url>/api/mcp, with its Authorization header from http_headers_helper. With --insecure-tls, a stdio entry running mcp --remote.

The command in an entry is this CLI's own absolute path with symlinks resolved, and install warns when that path is a temporary location that will not last. On Windows, when more than one Claude package is installed, install cannot tell which one you run and requires --config-path.

No key in the client's config

An entry names the profile, never the key. A stdio entry runs clika-cli --profile <name> mcp --remote, which reads the key from the profile when the client starts it. An HTTP entry's header helper runs mcp headers:

clika-cli --profile <name> mcp headers

mcp headers prints {"Authorization":"Bearer <key>"} from the profile and makes no request to the platform. It is the command headersHelper (Claude Code) and http_headers_helper (Codex) run, and it is not listed in clika-cli mcp --help. Because every entry reads the key from the profile, rotating or revoking a key needs a new login and no change to any client.

Only marked entries are touched

Each entry install writes carries a marker, clika-cli:<profile>: in the CLIKA_MCP_MANAGED_BY environment variable of a stdio entry, or in the static X-Clika-Managed-By header of an HTTP entry (headers in Claude Code, http_headers in Codex). The server ignores both. install, uninstall and status act on marked entries only:

• Running install again updates this profile's entry in place, under whatever name it has now.
• A new entry is created under --name. A name already held by an entry without this profile's marker is refused, and nothing is changed.
• uninstall removes every entry carrying this profile's marker. An entry written by hand, or by another profile, is left alone.

The rest of the file is kept as it was: only the entry's bytes change, and every other key keeps its order and formatting. The write is atomic and keeps the file's permissions, and when something changed the previous content is saved next to it as <file>.bak.

Restarting the client

A client reads its config when it starts. When the client's app is running (a Claude Code session, Claude Desktop, a Codex session or ChatGPT Desktop), install and uninstall print one line saying so and that a restart loads or removes the server. Restart it. Nothing is printed when it is not running.

tools

clika-cli tools [flags]

Lists every documented operation as <tool-name> <METHOD> <path>. The tool name is what call takes, and what an MCP tools/call takes, so this is how you find the name for an operation you can see in the API.

Flag	Type	Default	Meaning
--tag	string	none	Filter by the operation's API tag, for example devices or jobs.

$ clika-cli tools --tag devices
get_devices               GET     /api/devices
post_devices              POST    /api/devices
get_devices_id            GET     /api/devices/{id}
put_devices_id            PUT     /api/devices/{id}
delete_devices_id         DELETE  /api/devices/{id}
post_devices_id_exec      POST    /api/devices/{id}/exec

clika-cli tools | wc -l
clika-cli tools --tag jobs

call

clika-cli call <tool-name> [key=value ...] [flags]

Invokes one operation by tool name, with flat key=value arguments. Path and query parameters come from the API description; the request body is body=<json> or body=@path/to/file.json.

Flag	Type	Default	Meaning
--raw	bool	false	Print the response body byte for byte, with no pretty-printing.

clika-cli call get_devices
clika-cli call get_devices_id id=1f0a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8
clika-cli call post_job_definitions body=@./job-def.json
clika-cli call post_models body='{"huggingface_url":"Qwen/Qwen2.5-0.5B-Instruct"}'

call uses the same dispatch path as the MCP server, so call <tool> and an assistant's tools/call <tool> produce identical results. That makes it the right way to reproduce something an assistant did, or to check what a tool will return before handing it to one.

For everyday use prefer the resource subcommands. clika-cli devices list is call get_devices with tables, filters as flags and name resolution added.

What an assistant sees

A tools/list returns every tool with its input schema. A tools/call dispatches the matching HTTP request and returns the response body as text, pretty-printed when it is JSON. A non-2xx response comes back as an in-band error result rather than a protocol failure, so the model can read the message and correct itself.

Operations that require a multipart/form-data upload are flagged in their tool descriptions. An assistant cannot call those, since a tool call is sent as JSON. A file still reaches the platform through the chunked upload session (POST /api/artifacts/uploads, then one base64-encoded chunk per call) or an external source the platform fetches itself (POST /api/artifacts/external), and from a terminal with artifacts upload or devices push. See artifacts and devices.

Full command reference

Every command below is generated from the deployment's own API description, so one subcommand is exactly one platform operation. Each entry names the method, the endpoint and the MCP tool name, so the same operation is identifiable whichever surface you drive it from. Path parameters are positional arguments, query parameters are flags, and a request body is --body or --body-file. The hand-written commands, the ones that stream, propagate an exit code, or hand your terminal to ssh, carry no operation line.

The prose above covers the commands most people reach for. This section is the complete surface, for when you need the flag you have not used before.

clika-cli mcp

mcp has 3 subcommands.

clika-cli mcp install

Adds an entry for the platform's MCP server to the client's own config file (claude-code, claude-desktop, codex). The entry names the profile, never the key: the client gets the key from this CLI when it connects. Run login first, or answer yes when install offers to.

clika-cli mcp install <client> [flags]

Positional arguments: required <client>.

Flag	Type	Default	Meaning
--config-path	string	none	the client's config file, instead of the detected one
--dry-run	bool	false	print the change and write nothing
--name	string	"clika-platform"	entry name for a new entry (an entry this profile installed keeps its name)

clika-cli mcp status

For each client (claude-code, claude-desktop, codex), says whether mcp install registered the server there, under which entry name and profile, which config file was read, and why that file.

clika-cli mcp status [flags]

clika-cli mcp uninstall

Removes every entry in the client's config that mcp install added for this profile (claude-code, claude-desktop, codex). An entry written by hand, or by another profile, is left alone.

clika-cli mcp uninstall <client> [flags]

Positional arguments: required <client>.

Flag	Type	Default	Meaning
--config-path	string	none	the client's config file, instead of the detected one
--dry-run	bool	false	print the change and write nothing

clika-cli tools

clika-cli tools

Lists every documented operation outside the platform-admin API as <tool-name> <METHOD> <path>. The tool name is what call and an MCP tools/call take.

clika-cli tools [flags]

Flag	Type	Default	Meaning
--tag	string	none	filter by OpenAPI tag (e.g. devices, jobs)

clika-cli call

clika-cli call

Invokes the named tool (see the tools subcommand). Arguments are key=value pairs. Path/query parameters come from the spec; the request body is provided as body=<json> or body=@path/to/file.json.

clika-cli call <tool-name> [key=value ...] [flags]

Positional arguments: required <tool-name>; optional [key=value ...].

Flag	Type	Default	Meaning
--raw	bool	false	print raw response without pretty-printing

Related

• Using with AI (MCP): connecting Claude Desktop, Claude Code, Codex and other clients, step by step.
• Authentication and profiles: the credential the server presents, and scoping an API key.
• CLI overview: how the CLI, the API and MCP relate to one another.