DesktopCommanderMCP Tool Call Origin Explained: 'ui' vs 'llm' Schemas

In DesktopCommanderMCP, the origin field distinguishes between calls initiated by built-in UI widgets ('ui') and those triggered by LLM agents ('llm'), solely to determine whether the call is excluded from or included in telemetry logging.

DesktopCommanderMCP is an open-source Model Context Protocol (MCP) server that exposes filesystem and process management capabilities to AI assistants. The origin parameter appears across tool argument schemas in src/tools/schemas.ts and serves as a metadata flag that governs telemetry behavior without affecting actual tool execution or return values.

What the Origin Field Signifies

The origin field is a string literal type defined on most tool argument schemas. It accepts two possible values:

• 'ui' – Indicates the request originated from the built-in UI widgets, such as the file preview panel, configuration editor, or terminal interface.
• 'llm' (or omission) – Indicates the request came from an LLM-driven assistant or external agent invoking the tool programmatically.

This distinction exists purely for classification purposes. According to the source code comments in src/tools/schemas.ts, the 'ui' value specifically signals that the call should be excluded from analytics tracking.

How Origin Affects Telemetry Logging

The practical impact of the origin field manifests in the server's telemetry pipeline. When processing tool calls, DesktopCommanderMCP checks the origin value to determine whether to emit usage metrics.

UI-originated calls (origin: 'ui') are excluded from telemetry collection. This prevents internal UI interactions—such as automatically refreshing a file preview or updating configuration settings—from polluting usage analytics or incurring unnecessary logging overhead.

LLM-originated calls (when origin is 'llm' or undefined) are recorded in telemetry streams. This enables accurate usage statistics, cost accounting, and debugging information for actual LLM agent interactions.

The relevant detection logic appears in src/server.ts around lines 1253–1255, where the server calculates isUiOriginCall and conditionally skips telemetry logging:

// src/server.ts (excerpt)
const isUiOriginCall = !!(args && typeof args === 'object' && (args as any).origin === 'ui');
if (isUiOriginCall) {
  // Telemetry logging is bypassed for UI calls
} else {
  // Call is recorded for analytics and cost tracking
}

View implementation

Source Code Implementation

Schema Definitions in schemas.ts

The origin field is defined consistently across tool argument schemas using Zod. For example, ReadFileArgsSchema includes the field with a comment explaining its telemetry purpose:

// src/tools/schemas.ts
export const ReadFileArgsSchema = z.object({
  path: z.string(),
  offset: z.number().optional(),
  length: z.number().optional(),
  // 'ui' origin calls are excluded from telemetry
  origin: z.enum(['ui', 'llm']).optional(),
});

Similarly, WriteFileArgsSchema carries the same annotation at lines 78–80, confirming that this pattern applies to all file and process operations within the codebase. These definitions ensure type safety while documenting the telemetry exclusion contract directly in the schema.

Telemetry Logic in server.ts

The runtime enforcement occurs in the request handler. When a tool call arrives, the server destructures the arguments and evaluates the origin flag before invoking the underlying function. If the flag equals 'ui', the telemetry middleware is bypassed entirely, preventing the call from reaching analytics pipelines.

Practical Usage Examples

UI Widget Calls with origin: 'ui'

Internal UI components explicitly set origin: 'ui' when invoking tools to avoid telemetry noise. For instance, the file preview panel calls read_file with this flag when loading content for display:

// Inside a UI widget (e.g., file-preview)
await options.callTool?.('read_file', {
  path: '/etc/hosts',
  offset: 0,
  length: 200,
  origin: 'ui'  // Explicitly marks this as UI-originated
});

This pattern appears in [src/ui/file-preview/src/panel-actions.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/ui/file-preview/src/panel-actions.ts#L124-L144) and [src/ui/config-editor/src/app.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/ui/config-editor/src/app.ts#L441-L473), where widgets call tools like start_process and get_config with the UI origin flag.

LLM Agent Calls with origin: 'llm'

When LLM agents or external clients invoke tools, they either omit the origin field or explicitly set it to 'llm'. This ensures the call is recorded in telemetry for usage tracking:

// LLM agent invocation
await callTool('read_file', {
  path: '/etc/hosts',
  offset: 0,
  length: 200,
  origin: 'llm'  // Explicitly marks this as LLM-originated (or omit entirely)
});

Omitting the field produces identical telemetry behavior, as the server treats undefined origins as LLM calls by default.

Summary

• The origin field in DesktopCommanderMCP tool schemas accepts 'ui' or 'llm' to identify the call source.
• origin: 'ui' excludes the call from telemetry logging, while origin: 'llm' (or omission) includes it.
• The distinction is implemented in [src/server.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts#L1253-L1255) via the isUiOriginCall check and defined in [src/tools/schemas.ts](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/schemas.ts) across schemas like ReadFileArgsSchema.
• UI widgets pass 'ui' to prevent internal operations from skewing analytics, whereas LLM agents rely on the default 'llm' behavior for proper usage tracking.

Frequently Asked Questions

Does the origin field change how the tool executes?

No. The origin field is purely a metadata flag used for telemetry classification. Whether set to 'ui', 'llm', or omitted, the underlying tool logic executes identically, performing the same file reads, writes, or process operations.

What happens if the origin field is omitted?

When origin is undefined, the server defaults to treating the call as LLM-originated. Consequently, the call is included in telemetry logging, usage statistics, and cost accounting, exactly as if origin: 'llm' had been explicitly specified.

Where is the telemetry exclusion logic implemented?

The exclusion logic resides in src/server.ts around lines 1253–1255. The code computes isUiOriginCall by checking if args.origin === 'ui', then conditionally bypasses the telemetry logging branch for UI calls while recording all other invocations.

Can external clients use origin: 'ui' to avoid telemetry?

While technically possible, setting origin: 'ui' from external clients would violate the semantic contract of the API. This flag is reserved for internal UI widgets to distinguish user-initiated actions from programmatic LLM calls. Third-party clients should omit the field or use 'llm' to ensure accurate analytics.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}