MCP Sidecar MCP server

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 SIDECARMAXOUTPUT_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

Shortened. The full README is on GitHub.