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

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 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 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 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, 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 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, which specifies that 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

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:

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:

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, 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 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 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 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.

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