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.

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

Tool	Description	Parameters	Returns
start	Spawn a background process	command, name?, cwd?, env?	{ id, name, pid }
stop	Terminate a process (graceful, then force)	id	{ id, exitCode, uptime }
list	List all managed processes	--	[{ id, name, pid, state, uptime }]
output	Get buffered stdout/stderr	id, tail?, maxBytes?	{ stdout, stderr, uptime }
send	Write to a process's stdin	id, input	{ ok }
status	Get detailed state of one process	id	{ id, name, pid, state, exitCode, uptime, outputSize }

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

State	Meaning
running	Process is alive
exited	Process terminated normally
failed	Process terminated with non-zero exit code
killed	Process was stopped via the stop tool

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):

Variable	Default	Description
SIDECAR_MAX_PROCESSES	10	Maximum concurrent processes
SIDECAR_BUFFER_SIZE	1048576 (1MB)	Output buffer size per process in bytes
SIDECAR_KILL_TIMEOUT	5000	Milliseconds to wait between SIGTERM and SIGKILL
SIDECAR_CLEANUP_AFTER	1800 (30 min)	Seconds before exited processes are auto-removed. 0 = disabled
SIDECAR_MAX_OUTPUT_SIZE	0 (unlimited)	Global cap on bytes returned by the output tool. 0 = no limit
SIDECAR_ALLOWED_EXECUTABLES	--	Comma-separated allowlist of executables (enables secure mode)
SIDECAR_BLOCKED_PATTERNS	--	Comma-separated regex patterns to reject commands
SIDECAR_AUDIT_LOG	--	Audit log directory, or true (cwd) / temp (OS temp dir)

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:

	Shell mode (default)	Secure mode
Execution	Via sh -c / cmd /C	Direct exec (no shell)
Allowlist	None	Only listed executables can run
Metacharacters	Allowed (shell interprets them)	Rejected (|, &, ;, >, <, $, `, (, ))
Blocked patterns	None	Regex patterns matched against full command
Audit logging	None	Optional JSONL log of all start/stop/blocked events

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:

Value	Log file location
true	./sidecar-audit.jsonl (current working directory)
temp	<OS temp dir>/sidecar-audit.jsonl
./logs	./logs/sidecar-audit.jsonl (directory auto-created)

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:

Allowlist entry	Matches
dotnet	dotnet anywhere (basename match)
./build.sh	Only ./build.sh (exact match)
/usr/bin/python3	Only /usr/bin/python3, or any python3 resolved via PATH

Distribution

Channel	Usage
npm	npx -y mcp-sidecar (platform binary via @mcp-sidecar/* optional packages)
GitHub Releases	Pre-built binaries attached to each release
MCP Registry	io.github.lsequeiraa/mcp-sidecar

License

MIT