mcp-sidecar

A lightweight, cross-platform MCP server for managing background processes. Built in Go for single-binary distribution with zero runtime dependencies.

Why?

AI coding agents (Claude Code, Gemini CLI, Cursor, etc.) lack the ability to run long-lived processes while continuing to interact with them. Common workflows affected:

• Start an API server, wait for it to be ready, then run HTTP requests against it

• Run a build in watch mode while editing code

• Start a database, seed it, run tests, tear it down

mcp-sidecar solves this by exposing process lifecycle management as MCP tools over stdio transport.

Related MCP server: MCP Background Job Server

Features

• Cross-platform -- Windows, Linux, macOS from a single codebase

• Zero dependencies -- Single Go binary, no runtime required

• Minimal surface -- 6 tools, no unnecessary complexity

• Reliable cleanup -- All child processes are terminated when the server exits; exited processes are auto-removed after a configurable TTL

• Output control -- Per-request maxBytes and global SIDECAR_MAX_OUTPUT_SIZE to cap output returned to the LLM

• Command security -- Optional executable allowlist, blocked patterns, and audit logging

Installation

Quick Setup (any agent)

The fastest way to install mcp-sidecar into any supported coding agent:

# Interactive -- detects installed agents and lets you pick
npx add-mcp mcp-sidecar

# Install to a specific agent
npx add-mcp mcp-sidecar -a claude-code
npx add-mcp mcp-sidecar -a cursor
npx add-mcp mcp-sidecar -a vscode

# Install to all detected agents
npx add-mcp mcp-sidecar --all

Supported agents: Claude Code, Codex, Cursor, VS Code, Gemini CLI, OpenCode, Zed, Goose, Cline, and more. See add-mcp for the full list.

Manual Configuration

Claude Code:

claude mcp add sidecar -- npx -y mcp-sidecar

opencode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "sidecar": {
      "type": "local",
      "command": ["npx", "-y", "mcp-sidecar"],
      "enabled": true
    }
  }
}

Generic (mcp.json):

{
  "mcpServers": {
    "sidecar": {
      "command": "npx",
      "args": ["-y", "mcp-sidecar"]
    }
  }
}

From Source

go install github.com/lsequeiraa/mcp-sidecar@latest

Pre-built binaries are also available on GitHub Releases for windows/amd64, linux/amd64, darwin/arm64, and darwin/amd64.

Tools

The uptime field reflects actual runtime: for running processes it's the time since start; for exited processes it's the time the process was alive (not the time since start).

The output tool's maxBytes parameter caps the total bytes of stdout+stderr combined. When both tail and maxBytes are provided, tail selects lines first, then maxBytes caps the byte size of the result. When the output exceeds the limit, the most recent content is kept and stderr is prioritized. Truncation preserves line boundaries. When output is truncated, the response includes "truncated": true and "totalBytes" indicating the original size.

Process States

Example workflow

A typical session where an agent starts an API server, waits for it to be ready, tests it, and tears it down:

1. start  { command: "dotnet run --project MyApi", name: "api" }
   → { id: "sc-a1b2c3", name: "api", pid: 12345 }

2. output { id: "sc-a1b2c3", tail: 5 }
   → { stdout: "Now listening on: http://localhost:5000", stderr: "", uptime: "3s" }

3. (agent runs curl http://localhost:5000/health using its own shell)

4. output { id: "sc-a1b2c3", tail: 20 }
   → { stdout: "...request logs...", stderr: "", uptime: "15s" }

5. stop   { id: "sc-a1b2c3" }
   → { id: "sc-a1b2c3", exitCode: -1, uptime: "18s" }

The agent uses its native shell for short-lived commands (curl, build tools, etc.) and mcp-sidecar for processes that need to stay alive across multiple tool calls.

Configuration

All configuration is via environment variables (all optional):

Auto-cleanup note: When SIDECAR_CLEANUP_AFTER is enabled (the default), exited processes are removed from the manager after the TTL expires. Once removed, calls to output, status, or stop for that process ID will return "not found". Retrieve any output you need within the TTL window (30 minutes by default).

Security

When SIDECAR_ALLOWED_EXECUTABLES is set, mcp-sidecar switches from shell mode to secure mode:

Metacharacters inside quotes are allowed -- grep "error|warning" file.txt works because the | is inside double quotes and won't be interpreted by a shell.

Backslash (\) is intentionally **not** treated as a metacharacter so Windows paths like C:\Users\me\app.exe work without escaping.

Configuration examples

Claude Desktop / Cursor (mcp.json):

{
  "mcpServers": {
    "sidecar": {
      "command": "npx",
      "args": ["-y", "mcp-sidecar"],
      "env": {
        "SIDECAR_ALLOWED_EXECUTABLES": "dotnet,npm,node,git,python",
        "SIDECAR_BLOCKED_PATTERNS": "rm\\s+-rf,--force,--no-verify",
        "SIDECAR_AUDIT_LOG": "./logs"
      }
    }
  }
}

Claude Code:

claude mcp add sidecar \
  -e SIDECAR_ALLOWED_EXECUTABLES=dotnet,npm,node,git,python \
  -e SIDECAR_BLOCKED_PATTERNS="rm\\s+-rf,--force,--no-verify" \
  -e SIDECAR_AUDIT_LOG=true \
  -- npx -y mcp-sidecar

Audit log format

The audit log is always written to a file named sidecar-audit.jsonl inside the configured directory. The SIDECAR_AUDIT_LOG variable controls where:

Each line is a JSON object with one of three event types:

{"ts":"2025-03-12T10:00:00Z","event":"start","id":"abc123","command":"dotnet run","cwd":"/app"}
{"ts":"2025-03-12T10:00:05Z","event":"stop","id":"abc123","exit_code":0,"duration":"5s"}
{"ts":"2025-03-12T10:00:06Z","event":"blocked","command":"rm -rf /","reason":"executable \"rm\" is not in allowed list"}

Executable matching

The allowlist supports three matching modes:

Distribution

License

MIT