# How Desktop Commander Uses the @modelcontextprotocol/sdk

> Discover how Desktop Commander uses the @modelcontextprotocol/sdk to build a Model-Context Protocol server and client for system tools and remote device integration.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-07-26

---

**Desktop Commander leverages the @modelcontextprotocol/sdk to implement a Model-Context Protocol server for exposing system tools and a client for remote device integration via STDIO transport.**

Desktop Commander (wonderwhy-er/DesktopCommanderMCP) is an open-source implementation of the Model-Context Protocol (MCP) that enables AI assistants to execute file operations, manage processes, and perform system searches. The project builds its entire architecture on the **@modelcontextprotocol/sdk** package (version `^1.9.0` as specified in [`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json)) to handle protocol negotiation, JSON-RPC communication, and request validation. By utilizing both the server and client components provided by the SDK, Desktop Commander creates a complete bidirectional bridge between AI models and local desktop environments.

## Server-Side Architecture Using @modelcontextprotocol/sdk

The core MCP server implementation resides in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts), where Desktop Commander instantiates a protocol-compliant server that advertises capabilities and handles tool invocations.

### Creating the MCP Server Instance

The server initialization imports the `Server` class from `@modelcontextprotocol/sdk/server/index.js` and configures it with identity metadata and capability declarations.

```typescript
// src/server.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

export const server = new Server(
  { name: "desktop-commander", version: VERSION },
  { capabilities: { tools: {}, resources: {}, prompts: {}, logging: {} } }
);

```

The `capabilities` object informs connecting clients which feature sets are available—tools for file system operations, resources for data access, prompts for templating, and logging for telemetry. The server relies on the SDK to manage protocol version negotiation and JSON-schema conversion through utilities like `zodToJsonSchema`.

### Registering Tool Handlers and Request Schemas

Desktop Commander registers specific handlers for each MCP request schema imported from `@modelcontextprotocol/sdk/types.js`. These handlers validate incoming requests and route them to internal implementations.

```typescript
import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{ name: "read_file", description: "Read a file", /* ... */ }],
}));

```

Each handler receives protocol-compliant requests (such as `CallToolRequestSchema` for tool execution or `ReadResourceRequestSchema` for resource access) and returns standardized responses. The SDK manages request validation, ensuring that all communication follows the Model-Context Protocol specification.

## Client Implementation for Remote Integration

For remote device scenarios, Desktop Commander implements an MCP client in [`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts) that communicates with the local server via STDIO transport.

### STDIO Transport Configuration

The client utilizes `StdioClientTransport` from `@modelcontextprotocol/sdk/client/stdio.js` to spawn the local Desktop Commander CLI as a child process and establish a bidirectional byte stream.

```typescript
// src/remote-device/desktop-commander-integration.ts
import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';

this.mcpTransport = new StdioClientTransport({
  ...config,
  env: { ...getDefaultEnvironment(), ...config.env, DC_REMOTE_DEVICE: 'true' },
});

```

The transport handles message framing, JSON parsing, and request-response correlation automatically. The `getDefaultEnvironment` function ensures proper environment variable inheritance while adding the `DC_REMOTE_DEVICE` flag to identify remote origins.

### Client Connection and Tool Invocation

After establishing transport, the code creates a `Client` instance from `@modelcontextprotocol/sdk/client/index.js` and initiates the protocol handshake.

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';

this.mcpClient = new Client(
  { name: "desktop-commander-client", version: "1.0.0" },
  { capabilities: {} }
);
await this.mcpClient.connect(this.mcpTransport);

```

Once connected, the client can invoke `callTool`, `listTools`, and other MCP operations. The client wrapper adds metadata (`_meta: { remote: true }`) to each tool call, allowing the server to attribute actions to remote clients appropriately.

## Complete Protocol Workflow

The end-to-end integration between the SDK's server and client components follows this sequence:

1. **Server Startup**: The local Desktop Commander server ([`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)) launches and begins listening on STDIO for incoming connections.
2. **Client Initialization**: A remote UI (such as a VS Code extension) loads the `DesktopCommanderIntegration` class, spawns the local CLI, and creates a `StdioClientTransport`.
3. **Handshake**: The `Client` connects via `client.connect(transport)`, performing protocol version negotiation through the SDK's built-in mechanisms.
4. **Tool Execution**: When the UI requests a tool (e.g., `read_file`), it executes `client.callTool({ name: "read_file", arguments: { path: "/etc/hosts" } })`.
5. **Server Processing**: The server receives the request, validates it against `CallToolRequestSchema`, executes the internal file system operation, and returns a protocol-compliant response.
6. **Result Delivery**: The SDK transport decodes the response and resolves the original promise back to the remote UI.

This workflow demonstrates how `@modelcontextprotocol/sdk` handles all transport plumbing, request validation, and JSON-RPC message formatting, allowing Desktop Commander to focus on business logic.

## Key SDK Components and File References

| Component | SDK Path | Purpose in Desktop Commander |
|-----------|----------|------------------------------|
| **Server** | `@modelcontextprotocol/sdk/server/index.js` | Creates the MCP server instance in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) |
| **Client** | `@modelcontextprotocol/sdk/client/index.js` | Implements remote device connectivity in [`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts) |
| **STDIO Transport** | `@modelcontextprotocol/sdk/client/stdio.js` | Provides `StdioClientTransport` and `getDefaultEnvironment` for process-based communication |
| **Request Schemas** | `@modelcontextprotocol/sdk/types.js` | Supplies validation schemas like `ListToolsRequestSchema` and `CallToolRequestSchema` |

The test suite in [`test/test-conditional-tools.js`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/test/test-conditional-tools.js) additionally verifies remote tool behavior using the same `Client` and `StdioClientTransport` classes, ensuring protocol compliance across versions.

## Summary

- Desktop Commander uses `@modelcontextprotocol/sdk` version `^1.9.0` to implement both MCP server and client functionality.
- The **Server** class in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) handles tool registration, capability advertisement, and request validation using SDK-provided schemas.
- The **Client** class with **StdioClientTransport** enables remote device integration by proxying tool calls from external UIs to the local server.
- The SDK manages all protocol-level concerns including JSON-RPC framing, version negotiation, and message validation, allowing the project to focus on file system and process management logic.

## Frequently Asked Questions

### What version of @modelcontextprotocol/sdk does Desktop Commander require?

Desktop Commander specifies `"@modelcontextprotocol/sdk": "^1.9.0"` in its [`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json) dependency list. This version provides the `Server`, `Client`, and `StdioClientTransport` classes along with the request schema types used throughout the codebase.

### How does Desktop Commander handle transport layer communication?

The project uses `StdioClientTransport` from the SDK's client module to wrap the Desktop Commander CLI as a child process. This transport handles bidirectional byte streaming over standard input/output, managing message framing and JSON parsing automatically while the SDK correlates requests with responses.

### Can the Desktop Commander server handle multiple simultaneous client connections?

While the SDK supports multiple transport types, Desktop Commander's current implementation in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) primarily operates via STDIO, which naturally supports one active client connection per process instance. For remote scenarios, each remote device spawns its own server process and client transport pair, as implemented in [`src/remote-device/desktop-commander-integration.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/desktop-commander-integration.ts).

### What is the purpose of the DC_REMOTE_DEVICE environment variable?

The `DC_REMOTE_DEVICE` flag is injected into the environment via `getDefaultEnvironment()` when initializing `StdioClientTransport`. This metadata allows the server to identify incoming connections as originating from remote clients, enabling it to apply appropriate security policies or logging attribution for actions performed through the remote device integration layer.