diff --git a/packages/command-registry/src/flag-definitions-target.ts b/packages/command-registry/src/flag-definitions-target.ts index ac309721e4..0f774ed963 100644 --- a/packages/command-registry/src/flag-definitions-target.ts +++ b/packages/command-registry/src/flag-definitions-target.ts @@ -60,7 +60,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Proxy lease: OS version or range the backend picks the device by (Android: API level); refused without such a backend', inputDescription: - 'OS version or range for the device a proxy backend leases, for example 18.6.2 or ">=26" (Android: API level), sent as given. A blank string names nothing; a non-string fails with INVALID_ARGS, reason device-spec-invalid. Only the CLI allocating a lease through connect proxy sends it to that backend; a daemon refuses every other request that names it, with reason device-spec-unsupported.', + 'Proxy lease: OS version or range, for example 18.6.2 or ">=26" (Android: API level). Honored only by a proxy backend that leases by spec; other daemons refuse it.', projectConfig: false, recorded: false, }, @@ -72,7 +72,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Proxy lease: Android system image tag the backend picks the device by; refused without such a backend', inputDescription: - 'Android system image tag for the device a proxy backend leases, for example google_apis_playstore, sent as given. A blank string names nothing; a non-string fails with INVALID_ARGS, reason device-spec-invalid. Only the CLI allocating a lease through connect proxy sends it to that backend; a daemon refuses every other request that names it, with reason device-spec-unsupported.', + 'Proxy lease: Android system image tag, for example google_apis_playstore. Honored only by a proxy backend that leases by spec; other daemons refuse it.', projectConfig: false, recorded: false, }, @@ -84,7 +84,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Proxy lease: iOS simulator mode (slim or full) the backend leases; refused without such a backend', inputDescription: - 'iOS simulator mode for the device a proxy backend leases, slim or full, sent as given; the backend validates it. A blank string names nothing; a non-string fails with INVALID_ARGS, reason device-spec-invalid. Only the CLI allocating a lease through connect proxy sends it to that backend; a daemon refuses every other request that names it, with reason device-spec-unsupported.', + 'Proxy lease: iOS simulator mode, slim or full. Honored only by a proxy backend that leases by spec; other daemons refuse it.', projectConfig: false, recorded: false, }, @@ -96,7 +96,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Proxy lease: saved device state (baseline) the backend restores on the leased device; refused without such a backend', inputDescription: - 'Name of a saved, prepared device state (baseline) that a proxy backend restores on the device it leases, sent as given; the backend validates it. A blank string names nothing; a non-string fails with INVALID_ARGS, reason device-spec-invalid. A new lease that does not report this baseline in lease.device.baseline is released and fails with reason device-spec-unsupported. Only the CLI allocating a lease through connect proxy sends it to that backend; a daemon refuses every other request that names it, with reason device-spec-unsupported.', + 'Proxy lease: saved device state (baseline) to restore on the leased device. Honored only by a proxy backend that leases by spec; other daemons refuse it.', projectConfig: false, recorded: false, }, @@ -108,7 +108,7 @@ export const TARGET_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Proxy lease: ask the backend for a physical device instead of a simulator or emulator; refused without such a backend', inputDescription: - 'Ask a proxy backend to lease a physical device instead of a simulator or emulator. false names nothing; a non-boolean fails with INVALID_ARGS, reason device-spec-invalid. Only the CLI allocating a lease through connect proxy sends true to that backend; a daemon refuses every other request that names it, with reason device-spec-unsupported.', + 'Proxy lease: true requests a physical device; false selects nothing. Honored only by a proxy backend that leases by spec; other daemons refuse it.', projectConfig: false, recorded: false, }, diff --git a/packages/command-registry/src/flag-definitions-workflow.ts b/packages/command-registry/src/flag-definitions-workflow.ts index d1e82d5b67..a3ce7f70cd 100644 --- a/packages/command-registry/src/flag-definitions-workflow.ts +++ b/packages/command-registry/src/flag-definitions-workflow.ts @@ -99,7 +99,7 @@ export const WORKFLOW_FLAG_DEFINITIONS: readonly FlagDefinition[] = [ usageDescription: 'Open: wait up to n ms for a device another session is holding before failing with DEVICE_IN_USE', inputDescription: - "Block this open for up to n milliseconds (100-120000) while another session holds the device, then fail with DEVICE_IN_USE naming that session. Only session contention is waited for: a device claim held by another workspace is refused at once with its recovery command. A device that never frees, or is taken again while this open waits, costs the full budget, which extends this command's timeout envelope rather than eating into it.", + "Wait up to n milliseconds (100-120000) while another session holds the device, then fail with DEVICE_IN_USE. A claim held by another workspace fails at once. The wait extends this command's timeout.", projectConfig: false, recorded: false, }, diff --git a/packages/command-surface/src/__tests__/command-surface-metadata.test.ts b/packages/command-surface/src/__tests__/command-surface-metadata.test.ts index bde58cad35..31e74b7f10 100644 --- a/packages/command-surface/src/__tests__/command-surface-metadata.test.ts +++ b/packages/command-surface/src/__tests__/command-surface-metadata.test.ts @@ -239,9 +239,9 @@ test('command family facets keep daemon writers as an explicit projection subset // fails instead of shipping a cross-surface mismatch. test('every emitted input schema carries the aligned device-selector descriptions', () => { const expected: Record = { - device: 'Device name selector (a UDID belongs in udid, a serial in serial).', - udid: 'Apple device or simulator UDID; the selector that pins one device when several share a name.', - serial: 'Android, HarmonyOS, or Vega VVD serial selector.', + device: 'Device name; ids go in udid or serial.', + udid: 'Apple device or simulator UDID.', + serial: 'Android, HarmonyOS, or Vega VVD serial.', }; let pinned = 0; for (const metadata of listCommandMetadata()) { diff --git a/packages/command-surface/src/common-input-fields.ts b/packages/command-surface/src/common-input-fields.ts index 14df32456c..1939b6011f 100644 --- a/packages/command-surface/src/common-input-fields.ts +++ b/packages/command-surface/src/common-input-fields.ts @@ -83,11 +83,12 @@ type CommonInputFieldSpec = { /** * The common operator shape: the value comes from the key's own environment - * variable or its `~/.agent-device/config.json` entry. It covers both kinds of + * variable or its `~/.agent-device/config.json` entry. It covers every kind of * operator-owned common key — the credential and the endpoint it is sent to * (a model-writable `daemonBaseUrl` would redirect the env-resolved - * `daemonAuthToken` to an arbitrary server), and the build and device-set paths, - * which select operator infrastructure rather than per-call work. + * `daemonAuthToken` to an arbitrary server), the build and device-set paths, + * which select operator infrastructure rather than per-call work, and the + * tenant, run, lease, and device-allowlist scope the connection is admitted under. */ const ENV_OR_OPERATOR_CONFIG = operatorAudience({ operatorConfig: true }); @@ -96,7 +97,7 @@ const RETIRED_READINESS_TIMEOUT_MESSAGE = const COMMON_INPUT_FIELDS = { session: { - schema: { type: 'string', description: 'Agent-device session name.' }, + schema: { type: 'string', description: 'Session name.' }, read: (record) => optionalString(record, 'session'), flagKey: 'session', flagIn: ['input'], @@ -105,7 +106,7 @@ const COMMON_INPUT_FIELDS = { schema: { type: 'string', enum: PLATFORM_SELECTORS, - description: 'Platform selector used to resolve a device.', + description: 'Device platform.', }, read: (record) => optionalEnum(record, 'platform', PLATFORM_SELECTORS), flagKey: 'platform', @@ -115,7 +116,7 @@ const COMMON_INPUT_FIELDS = { schema: { type: 'string', enum: DEVICE_TARGETS, - description: 'Device target form. Maps to the CLI --target flag.', + description: 'Device form factor.', }, read: readDeviceTarget, clientKey: 'target', @@ -127,14 +128,13 @@ const COMMON_INPUT_FIELDS = { schema: { type: 'string', enum: DEVICE_TARGETS, - description: - 'Alias for deviceTarget. Commands that take a UI target (ref, selector, or x/y) accept only deviceTarget.', + description: 'Alias for deviceTarget.', }, }, device: { schema: { type: 'string', - description: 'Device name selector (a UDID belongs in udid, a serial in serial).', + description: 'Device name; ids go in udid or serial.', }, read: (record) => optionalString(record, 'device'), flagKey: 'device', @@ -143,8 +143,7 @@ const COMMON_INPUT_FIELDS = { udid: { schema: { type: 'string', - description: - 'Apple device or simulator UDID; the selector that pins one device when several share a name.', + description: 'Apple device or simulator UDID.', }, read: (record) => optionalString(record, 'udid'), flagKey: 'udid', @@ -153,7 +152,7 @@ const COMMON_INPUT_FIELDS = { serial: { schema: { type: 'string', - description: 'Android, HarmonyOS, or Vega VVD serial selector.', + description: 'Android, HarmonyOS, or Vega VVD serial.', }, read: (record) => optionalString(record, 'serial'), flagKey: 'serial', @@ -206,6 +205,7 @@ const COMMON_INPUT_FIELDS = { description: 'Android serial allowlist used for device resolution.', }, read: (record) => optionalString(record, 'androidDeviceAllowlist'), + audience: ENV_OR_OPERATOR_CONFIG, flagKey: 'androidDeviceAllowlist', flagIn: ['input', 'selection'], }, @@ -241,14 +241,17 @@ const COMMON_INPUT_FIELDS = { tenant: { schema: { type: 'string', description: 'Remote tenant identifier.' }, read: (record) => optionalString(record, 'tenant'), + audience: ENV_OR_OPERATOR_CONFIG, }, runId: { schema: { type: 'string', description: 'Lease run identifier.' }, read: (record) => optionalString(record, 'runId'), + audience: ENV_OR_OPERATOR_CONFIG, }, leaseId: { schema: { type: 'string', description: 'Existing lease identifier.' }, read: (record) => optionalString(record, 'leaseId'), + audience: ENV_OR_OPERATOR_CONFIG, }, cwd: { schema: { type: 'string', description: 'Working directory for command execution.' }, diff --git a/packages/command-surface/src/management/app.ts b/packages/command-surface/src/management/app.ts index 4cf1ed22e2..90ac292b1f 100644 --- a/packages/command-surface/src/management/app.ts +++ b/packages/command-surface/src/management/app.ts @@ -77,7 +77,7 @@ const openCommandMetadata = defineFieldCommandMetadata( noRecord: booleanField('Do not record this action.'), metroHost: stringField('Session-scoped Metro/debug host hint applied to the opened app.'), metroPort: integerField( - 'Session-scoped Metro/debug port hint applied to the opened app. On an emulator/simulator the host defaults to the loopback alias (Android 10.0.2.2, iOS 127.0.0.1) when --metro-host is omitted; physical devices still require an explicit --metro-host.', + 'Session-scoped Metro/debug port hint applied to the opened app. Without metroHost, emulators and simulators use the loopback alias; physical devices need metroHost.', { min: 1, max: 65535, diff --git a/packages/command-surface/src/post-action-observation-grammar.ts b/packages/command-surface/src/post-action-observation-grammar.ts index 892cabed07..9c0e4e0062 100644 --- a/packages/command-surface/src/post-action-observation-grammar.ts +++ b/packages/command-surface/src/post-action-observation-grammar.ts @@ -34,7 +34,7 @@ const settleFields = () => ({ 'After the action, wait for the UI to go quiet and return the settled diff vs the pre-action tree in the same response. Best-effort; never fails the action.', ), settleQuietMs: integerField( - 'Settle: quiet window in milliseconds (default 500; 300 when the settled tree comes from the iOS simulator snapshot bridge). On iOS, a broad screen replacement such as a modal dismissal is confirmed for at least 1500ms whatever window is asked for, within the timeoutMs settle deadline; a replacement from a screen the pre-action capture read as presenting nothing, such as a tab switch, gets no 1500ms confirmation and keeps the asked window.', + 'Settle: quiet window in milliseconds (default 500; 300 on the iOS simulator snapshot bridge). On iOS, a broad replacement of a non-empty screen holds at least 1500ms within timeoutMs.', { min: 0 }, ), timeoutMs: integerField('Settle: wait deadline in milliseconds (default 10000).', { min: 1 }), diff --git a/packages/contracts/src/client-app.ts b/packages/contracts/src/client-app.ts index 61add7127e..a462387ed7 100644 --- a/packages/contracts/src/client-app.ts +++ b/packages/contracts/src/client-app.ts @@ -79,11 +79,9 @@ export type AppOpenOptions = AgentDeviceRequestOverrides & /** Startup budget in milliseconds: bounds the Simulator boot wait on a cold device. */ timeoutMs?: number; /** - * Block this open for up to n milliseconds (100-120000) while another session holds the device, - * then fail with DEVICE_IN_USE naming that session. Only session contention is waited for: a - * device claim held by another workspace is refused at once with its recovery command. A device - * that never frees, or is taken again while this open waits, costs the full budget, which - * extends this command's timeout envelope rather than eating into it. + * Wait up to n milliseconds (100-120000) while another session holds the device, then fail + * with DEVICE_IN_USE. A claim held by another workspace fails at once. The wait extends this + * command's timeout. */ waitMs?: number; // Editor documentation for a public type: a `.d.ts` is read where no diff --git a/src/mcp/__tests__/command-tools-operator-inputs.test.ts b/src/mcp/__tests__/command-tools-operator-inputs.test.ts index 3dae1b2263..351fd32fa4 100644 --- a/src/mcp/__tests__/command-tools-operator-inputs.test.ts +++ b/src/mcp/__tests__/command-tools-operator-inputs.test.ts @@ -9,8 +9,9 @@ import { createCommandToolExecutor, listCommandTools } from '../command-tools.ts // Operator-owned inputs are never model-writable: the model reads untrusted // app UI text and picks tool arguments, so no tool schema may offer a -// parameter to write a credential, the endpoint it is sent to, or an -// operator infrastructure path into (exfiltration/redirect path). The keys +// parameter to write a credential, the endpoint it is sent to, an +// operator infrastructure path, or the tenant/lease scope a connection is +// admitted under (exfiltration/redirect path). The keys // are refused as explicit input too — fail closed with env guidance, the // same posture as retired fields — while operator env/config defaults keep // flowing outside the model-writable surface. @@ -25,6 +26,10 @@ const OPERATOR_OWNED_KEYS = [ 'iosXctestrunFile', 'iosXctestDerivedDataPath', 'iosXctestEnvDir', + 'androidDeviceAllowlist', + 'tenant', + 'runId', + 'leaseId', ] as const; // The rest of the shared common input: keys a model may write, because they @@ -37,10 +42,6 @@ const MODEL_WRITABLE_COMMON_KEYS = [ 'device', 'udid', 'serial', - 'androidDeviceAllowlist', - 'tenant', - 'runId', - 'leaseId', 'debug', ] as const; @@ -215,6 +216,10 @@ test('MCP refuses any argument the advertised schema does not list', async () => test('MCP still resolves operator env values outside the model-writable surface', async () => { vi.stubEnv('AGENT_DEVICE_DAEMON_AUTH_TOKEN', 'operator-env-token'); vi.stubEnv('AGENT_DEVICE_STATE_DIR', '/operator/state-dir'); + vi.stubEnv('AGENT_DEVICE_TENANT', 'operator-tenant'); + vi.stubEnv('AGENT_DEVICE_RUN_ID', 'operator-run'); + vi.stubEnv('AGENT_DEVICE_LEASE_ID', 'operator-lease'); + vi.stubEnv('AGENT_DEVICE_ANDROID_DEVICE_ALLOWLIST', 'emulator-5554'); const createdConfigs: Array> = []; const calls: Array<{ name: string; input: Record }> = []; const executor = createCommandToolExecutor({ @@ -232,6 +237,10 @@ test('MCP still resolves operator env values outside the model-writable surface' assert.equal(result.isError, false); assert.equal(calls[0]?.input.daemonAuthToken, 'operator-env-token'); + assert.equal(calls[0]?.input.tenant, 'operator-tenant'); + assert.equal(calls[0]?.input.runId, 'operator-run'); + assert.equal(calls[0]?.input.leaseId, 'operator-lease'); + assert.equal(calls[0]?.input.androidDeviceAllowlist, 'emulator-5554'); assert.equal(createdConfigs[0]?.stateDir, '/operator/state-dir'); }); diff --git a/src/mcp/__tests__/command-tools-schema-budget.test.ts b/src/mcp/__tests__/command-tools-schema-budget.test.ts new file mode 100644 index 0000000000..0b50e4bdf9 --- /dev/null +++ b/src/mcp/__tests__/command-tools-schema-budget.test.ts @@ -0,0 +1,41 @@ +import assert from 'node:assert/strict'; +import { test } from 'vitest'; +import { COMMON_INPUT_AUDIENCE, listCommandMetadata } from '@agent-device/command-surface'; +import { listCommandTools } from '../command-tools.ts'; +import { CONFIG_LOADER_AUDIENCE, MCP_TOOL_CONFIG_AUDIENCE } from '../tool-control-fields.ts'; + +// Clients that compact large tool schemas drop descriptions and nested structure above about +// 5 KB, and clients that defer tool schemas append the full schema to every error result. +const INPUT_SCHEMA_BUDGET_BYTES = 5 * 1024; + +test('every MCP tool input schema stays within the byte budget', () => { + const oversized = listCommandTools() + .map((tool) => ({ + name: tool.name, + bytes: Buffer.byteLength(JSON.stringify(tool.inputSchema)), + })) + .filter((tool) => tool.bytes > INPUT_SCHEMA_BUDGET_BYTES); + assert.deepEqual(oversized, []); +}); + +test('no MCP tool advertises an operator-owned input', () => { + const audiences = [ + COMMON_INPUT_AUDIENCE, + MCP_TOOL_CONFIG_AUDIENCE, + CONFIG_LOADER_AUDIENCE, + ...listCommandMetadata().map((metadata) => metadata.inputAudience), + ]; + const operatorKeys = new Set( + audiences.flatMap((audience) => + Object.entries(audience).flatMap(([key, entry]) => (entry.kind === 'operator' ? [key] : [])), + ), + ); + for (const key of ['tenant', 'config', 'remoteConfig']) { + assert.ok(operatorKeys.has(key), `expected ${key} to be operator-owned`); + } + for (const tool of listCommandTools()) { + const properties = tool.inputSchema.properties ?? {}; + const advertised = [...operatorKeys].filter((key) => Object.hasOwn(properties, key)); + assert.deepEqual(advertised, [], `${tool.name} advertises operator-owned inputs`); + } +}); diff --git a/src/mcp/command-tools.ts b/src/mcp/command-tools.ts index d8fded948b..755d23ba99 100644 --- a/src/mcp/command-tools.ts +++ b/src/mcp/command-tools.ts @@ -6,7 +6,6 @@ import { isCommandName, listCommandMetadata, listMcpCommandMetadata, - operatorAudience, operatorInputRefusal, type AgentDeviceClient, type BindingSettings, @@ -32,6 +31,7 @@ import { } from '@agent-device/command-registry/registry'; import { MCP_COMMAND_OUTPUT_SCHEMAS } from './mcp-output-schemas.ts'; import { + CONFIG_LOADER_AUDIENCE, MCP_TOOL_CONFIG_AUDIENCE, MCP_TOOL_CONFIG_KEYS, mcpToolConfigProperties, @@ -82,24 +82,6 @@ type McpToolConfig = { outputFormat: McpOutputFormat; }; -/** - * Config-file-loading keys. Not per-command flags but flags the MCP config - * resolver reads to load an arbitrary file; never model-writable, since that - * file can carry operator credentials and endpoints. They appear in no tool - * schema, so admission rejects them like any unadvertised key — with a message - * that points at the operator path instead of the generic unknown-key text. - */ -const CONFIG_LOADER_AUDIENCE: InputAudienceMap = { - config: operatorAudience({ - operatorPath: - 'Point the process serving these tools at a config file with the AGENT_DEVICE_CONFIG environment variable.', - }), - remoteConfig: operatorAudience({ - operatorPath: - 'Configure the remote profile on the process serving these tools, not per tool call.', - }), -}; - /** * Every `operator` key any command declares. The deny side is deliberately * global rather than per-command: a screen that steers the model into writing a diff --git a/src/mcp/server-guide.ts b/src/mcp/server-guide.ts index 4f52e3ce13..ae509802cc 100644 --- a/src/mcp/server-guide.ts +++ b/src/mcp/server-guide.ts @@ -15,7 +15,7 @@ import type { ToolResult } from './command-tools.ts'; * `open`, act → settled diff → verify → `close`, ref fidelity, sparse-AX recovery, follow * error hints. Everything situational lives behind the `help` tool. */ -export const MCP_SERVER_INSTRUCTIONS = `agent-device drives iOS, Android, tvOS, Android TV, macOS, Linux, and web apps. Tools mirror CLI commands of the same name; CLI flags are camelCase properties (--settle -> settle: true). +export const MCP_SERVER_INSTRUCTIONS = `agent-device drives iOS, Android, tvOS, Android TV, macOS, Linux, and web apps. Tools mirror CLI commands of the same name; CLI flags are camelCase properties (--settle -> settle: true). If your client defers tool schemas, load a tool's schema before its first call. Start: known app -> call open {app, foreground: true} at once; do not probe with devices, apps, appstate, snapshot, or screenshot first. open returns the initial interactive snapshot with @refs. Unknown app id: devices, then apps, then open the discovered id; never invent ids. Existing session: continue from its state, do not reopen. diff --git a/src/mcp/tool-control-fields.ts b/src/mcp/tool-control-fields.ts index 768ffec2b3..08dd87d9e8 100644 --- a/src/mcp/tool-control-fields.ts +++ b/src/mcp/tool-control-fields.ts @@ -32,15 +32,13 @@ const MCP_TOOL_CONFIG_FIELDS = { schema: { type: 'string', enum: ['optimized', 'json'], - description: - 'MCP text content format. Defaults to optimized agent-friendly text; use json for JSON text and structured content from every tool.', + description: 'Result text: compact optimized (default) or the full result as JSON (larger).', }, }, includeCost: { schema: { type: 'boolean', - description: - 'Include per-command agent-cost (cost.wallClockMs, …) in structuredContent. Defaults to off; the default response shape is unchanged.', + description: 'Add agent cost (cost.wallClockMs, …) to the result.', }, }, responseLevel: { @@ -48,7 +46,7 @@ const MCP_TOOL_CONFIG_FIELDS = { type: 'string', enum: ['digest', 'default', 'full'], description: - 'Response verbosity: token-cheap digest / default (today) / full. Defaults to default; the default response shape is unchanged.', + 'Result detail: digest (smallest) or full (largest), as JSON; default is compact text.', }, }, } as const satisfies Record; @@ -61,6 +59,24 @@ export const MCP_TOOL_CONFIG_KEYS: ReadonlySet = new Set( MCP_TOOL_CONFIG_ROWS.map(([key]) => key), ); +/** + * Config-file-loading keys. Not per-command flags but flags the MCP config + * resolver reads to load an arbitrary file; never model-writable, since that + * file can carry operator credentials and endpoints. They appear in no tool + * schema, so admission rejects them like any unadvertised key — with a message + * that points at the operator path instead of the generic unknown-key text. + */ +export const CONFIG_LOADER_AUDIENCE: InputAudienceMap = { + config: operatorAudience({ + operatorPath: + 'Point the process serving these tools at a config file with the AGENT_DEVICE_CONFIG environment variable.', + }), + remoteConfig: operatorAudience({ + operatorPath: + 'Configure the remote profile on the process serving these tools, not per tool call.', + }), +}; + export const MCP_TOOL_CONFIG_AUDIENCE: InputAudienceMap = Object.fromEntries( MCP_TOOL_CONFIG_ROWS.flatMap(([key, field]) => (field.audience ? [[key, field.audience]] : [])), ); diff --git a/website/docs/docs/agent-setup.md b/website/docs/docs/agent-setup.md index 89562d8218..f519409b98 100644 --- a/website/docs/docs/agent-setup.md +++ b/website/docs/docs/agent-setup.md @@ -53,7 +53,7 @@ Capture screenshots, logs, network, audio, perf, traces, recordings, and `.ad` r `agent-device mcp` starts the stdio MCP server. It exposes installed CLI commands as structured tools. Some local workflows are CLI-only and have no MCP tool. -`agent-device mcp` accepts no flags or arguments other than `--help` and `--version`; any other argument fails with `INVALID_ARGS`. To configure the server, such as its state directory, set `AGENT_DEVICE_*` environment variables or `AGENT_DEVICE_CONFIG` in the client's server entry. +`agent-device mcp` accepts no flags or arguments other than `--help` and `--version`; any other argument fails with `INVALID_ARGS`. To configure the server, set `AGENT_DEVICE_*` environment variables or `AGENT_DEVICE_CONFIG` in the client's server entry. For example, set the state directory with `AGENT_DEVICE_STATE_DIR`, and the remote `tenant`, `runId`, and `leaseId` with `AGENT_DEVICE_TENANT`, `AGENT_DEVICE_RUN_ID`, and `AGENT_DEVICE_LEASE_ID` (or the same keys in `~/.agent-device/config.json`). Tool calls cannot pass these values. For web automation, MCP tools can target `platform: "web"` once the managed browser backend is set up, but `agent-device web setup` and `agent-device web doctor` are CLI-only. Run setup from a terminal that uses the same state directory as the MCP server before you ask an MCP client to drive a browser session.