# Understanding mcp-control.json in PI-Desktop: The MCP Control Plane Manifest

> Discover the purpose of mcp-control.json in PI-Desktop. This manifest file publishes local MCP control plane connection info, enabling external agents to connect and authenticate.

- Repository: [Lan/PI-Desktop](https://github.com/vastsa/PI-Desktop)
- Tags: deep-dive
- Published: 2026-09-12

---

**mcp-control.json is the manifest file that publishes the local MCP (Model Context Protocol) control plane’s connection information, enabling external agents to discover and authenticate to the HTTP-based MCP server running inside Electron Main.**

PI-Desktop is an open-source Electron application that optionally exposes a local MCP server for programmatic desktop automation. When the feature is activated via the `PI_DESKTOP_MCP_CONTROL` environment variable, the application writes an [`mcp-control.json`](https://github.com/vastsa/PI-Desktop/blob/main/mcp-control.json) file to the Electron user-data directory, serving as the single source of truth for external agents to locate and authenticate to the control plane.

## What is mcp-control.json?

The [`mcp-control.json`](https://github.com/vastsa/PI-Desktop/blob/main/mcp-control.json) file functions as a **discovery manifest** for the local MCP control plane. When PI-Desktop starts with the environment variable `PI_DESKTOP_MCP_CONTROL=1`, it launches an HTTP-based MCP server bound exclusively to a loopback address. Once the server is ready, it generates a cryptographically random 256-bit bearer token and persists the connection details to disk as a JSON record.

This manifest allows external scripts, automation tools, and integration agents to:
- Discover the exact URL where the MCP server is listening
- Obtain the bearer token required for authentication
- Verify the process ID of the running Electron instance
- Check whether the server is currently active or has shut down

## Manifest Contents and Security Properties

The JSON structure written to [`mcp-control.json`](https://github.com/vastsa/PI-Desktop/blob/main/mcp-control.json) contains four critical fields:

- **url**: The complete endpoint address (e.g., `http://127.0.0.1:PORT`) where the MCP server accepts connections
- **token**: The 256-bit bearer token required in the `Authorization` header for all API calls
- **pid**: The process ID of the Electron Main process hosting the server
- **active**: A boolean flag indicating whether the server is currently running (`true`) or has shut down (`false`)

Security is enforced at both the network and filesystem levels. According to the source code in [`apps/desktop/electron/main/mcp-control.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/electron/main/mcp-control.ts), the server binds exclusively to `127.0.0.1` to prevent remote network exposure. The manifest file itself is written with **POSIX mode `0600`**, ensuring only the file owner can read the sensitive bearer token contained within.

## Implementation in the Codebase

The manifest generation is implemented in [`apps/desktop/electron/main/mcp-control.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/electron/main/mcp-control.ts) within the `writeConnectionInfo` method (lines 70-75). This function is called immediately after the HTTP server successfully binds to a port and generates its authentication token.

The architectural design is documented in [`docs/adr/0203-local-mcp-control-plane.md`](https://github.com/vastsa/PI-Desktop/blob/main/docs/adr/0203-local-mcp-control-plane.md), which specifies that [`mcp-control.json`](https://github.com/vastsa/PI-Desktop/blob/main/mcp-control.json) serves as the contract between PI-Desktop and external automation agents. When the server initializes, it:

1. Generates a random 256-bit token stored in `mcp-control.token`
2. Echoes the same token into the JSON manifest
3. Writes the file to the Electron user-data directory with restricted permissions
4. Updates the `active` flag to `false` during graceful shutdown

## How to Read and Use mcp-control.json

External agents can locate the manifest in the Electron user-data directory and parse the JSON to obtain connection credentials. Below are practical examples for Node.js environments.

### Locating and Reading the Manifest

```javascript
import { readFileSync } from "node:fs";
import { join } from "node:path";

// Electron user-data directory (example on macOS)
const userDataDir = join(
  process.env.HOME,
  "Library",
  "Application Support",
  "PI Desktop"
);

// Load the JSON manifest
const manifestPath = join(userDataDir, "mcp-control.json");
const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));

console.log("MCP endpoint:", manifest.url);
console.log("Bearer token:", manifest.token);
console.log("Running PID:", manifest.pid);

```

### Making Authenticated MCP Requests

Once you have parsed the manifest, use the `url` and `token` fields to invoke MCP methods via HTTP POST requests:

```javascript
import fetch from "node-fetch";

async function callMcp(method, params = {}, token, url) {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${token}`,
      "Mcp-Protocol-Version": "2025-06-18",
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method,
      params,
    }),
  });

  return response.json();
}

// Example: get the desktop version
const result = await callMcp("app/getVersion", {}, manifest.token, manifest.url);
console.log(result);

```

### Detecting Server Availability

Always check the `active` flag before attempting to communicate with the server, as PI-Desktop updates this field when shutting down:

```javascript
if (!manifest.active) {
  console.warn("MCP control plane is not active – cannot issue commands.");
  process.exit(1);
}

```

## Summary

- **mcp-control.json** is the discovery manifest for PI-Desktop's local MCP control plane, written only when `PI_DESKTOP_MCP_CONTROL=1` is set.
- The file contains the **URL**, **bearer token**, **PID**, and **active status** required for external authentication and connection.
- Implemented in [`apps/desktop/electron/main/mcp-control.ts`](https://github.com/vastsa/PI-Desktop/blob/main/apps/desktop/electron/main/mcp-control.ts), specifically in the `writeConnectionInfo` method, with restrictive `0600` file permissions on POSIX systems.
- The server binds exclusively to `127.0.0.1` and uses cryptographically random 256-bit tokens to prevent unauthorized remote access.
- External agents must parse this JSON file from the Electron user-data directory to obtain the credentials needed for desktop automation via the MCP protocol.

## Frequently Asked Questions

### Where is mcp-control.json located on my system?

The file is stored in PI-Desktop's Electron user-data directory, which varies by operating system. On macOS, this is typically `~/Library/Application Support/PI Desktop/mcp-control.json`. On Linux, look in `~/.config/PI Desktop/`, and on Windows, check `%APPDATA%\PI Desktop\`. The exact path depends on where Electron stores application data for your platform.

### Is the MCP server enabled by default in PI-Desktop?

No. The MCP control plane is strictly opt-in. You must start PI-Desktop with the environment variable `PI_DESKTOP_MCP_CONTROL=1` for the server to launch and for [`mcp-control.json`](https://github.com/vastsa/PI-Desktop/blob/main/mcp-control.json) to be generated. Without this environment variable, the file will not exist and no local HTTP server will be exposed.

### How secure is the authentication mechanism?

The authentication relies on a cryptographically random 256-bit bearer token generated at startup and stored in [`mcp-control.json`](https://github.com/vastsa/PI-Desktop/blob/main/mcp-control.json) with `0600` permissions. Combined with the server's binding to `127.0.0.1` (loopback only), this prevents remote network attacks. However, any process running as the same user can read the file, so local system security remains important.

### What happens to mcp-control.json when PI-Desktop closes?

When the application shuts down gracefully, the server updates the `active` field in [`mcp-control.json`](https://github.com/vastsa/PI-Desktop/blob/main/mcp-control.json) to `false` so that monitoring agents immediately know the endpoint is unavailable. The file itself may persist on disk, but the boolean flag serves as the authoritative indicator of server status. If the process crashes, the file may retain `active: true` until the next startup.