Berth Documentation

The safe runtime & package manager for MCP servers.

Berth is a single-binary CLI that lets you discover, install, configure, run, and secure MCP servers — replacing manual JSON config editing with a clean developer experience and a real security layer.

Quick Start

cargo install berth

berth search github
berth install github
berth config github --set token=$GITHUB_TOKEN
berth start github
berth link claude-desktop

What’s Covered

Section	Topics
Installation	Binary installer, Homebrew, building from source
CLI Reference	All commands, flags, and registry API endpoints
Security Model	Permissions, audit trail, sandbox, org policy, encrypted secrets
Runtime Operations	Start/stop/restart, health checks, auto-restart, resource limits, global config
Client Integration	Claude Desktop, Cursor, Windsurf, Continue, VS Code, watch mode
Team Workflows	Config export/import, org policy, analytics

Install Methods

# Cargo
cargo install berth

# npm
npx @berth/cli search github

# Shell script
curl -fsSL https://raw.githubusercontent.com/berth-mcp/berth/main/install.sh | sh

# Homebrew (source)
brew install --HEAD ./Formula/berth.rb

Installation

Prerequisites

Rust 1.75+
C toolchain (gcc or clang)

Binary Installer

curl -fsSL https://raw.githubusercontent.com/berth-mcp/berth/main/install.sh | sh

Installer environment variables:

BERTH_VERSION (example: v0.1.0)
BERTH_INSTALL_DIR (example: $HOME/.local/bin)
BERTH_REPO (defaults to berth-mcp/berth)

Homebrew (source build)

brew install --HEAD ./Formula/berth.rb

Build From Source

git clone https://github.com/berth-mcp/berth.git
cd berth
cargo build --release

Binary path:

target/release/berth

Verify

./target/release/berth --help

CLI Reference

Core commands:

berth search <query>
berth info <server>
berth list
berth install <server[@version]>
berth import-github <owner/repo>
berth uninstall <server>
berth update <server|--all>
berth publish [manifest]
berth config <server>
berth config <server> --interactive
berth config <server> --set key=value --secure
berth config export [file]
berth config import <file>

Install runtimes supported by metadata:

Node (npx)
Python (uvx)
Binary artifacts (local path or URL)

Runtime commands:

berth start [server]
berth stop [server]
berth restart <server>
berth status [--health-check]
berth logs <server>
berth proxy <server>

Security commands:

berth permissions <server>
berth policy [server]
berth audit [server]
berth analytics [server]

Registry API command:

berth registry-api [--bind 127.0.0.1:8787] [--max-requests N]

Registry API endpoints:

GET /health
GET /servers with optional q|query, category, platform, trustLevel, offset, limit, sortBy, order
GET /servers/suggest with optional q|query, limit, category
GET /servers/facets with optional q|query, category, platform, trustLevel
GET /servers/filters
GET /servers/trending with optional limit, offset, category, platform, trustLevel
GET /stats with optional top
GET /servers/<name>
GET /servers/<name>/related with optional limit, offset
GET /servers/<name>/downloads
GET /servers/<name>/community
GET /servers/<name>/reports with optional limit, offset
GET /reports/filters
GET /reports with optional server, reason, offset, and limit
GET /analytics with optional server, since, and top
GET /publish/submissions with optional status, server, offset, and limit
GET /publish/submissions/filters
GET /publish/submissions/<id>
POST /publish/submissions/<id>/status with JSON body status and optional note
GET /publish/review-events with optional status, server, submission, offset, and limit
GET /publish/review-events/filters
GET /publishers with optional maintainer, verified, offset, and limit
GET /publishers/filters
GET /publishers/<maintainer>
POST /servers/<name>/star
POST /servers/<name>/report
GET /publishers/verified
POST /publishers/verify
POST /publishers/unverify
GET /site (HTML registry catalog with filters, sorting, and pagination query params)
GET /site/reports (HTML moderation feed with server, reason, limit, offset)
GET /site/submissions (HTML publish review queue with status, server, limit, offset)
GET /site/review-events (HTML publish review event feed with status, server, submission, limit, offset)
GET /site/publishers (HTML publisher verification dashboard with maintainer, verified, limit, offset)
GET /site/publishers/<maintainer> (HTML publisher detail page with maintainer signals and server list)
GET /site/analytics (HTML usage analytics dashboard with server, since, and top)
GET /site/submissions/<id> (HTML submission detail with manifest and quality checks)
GET /site/servers/<name> (HTML server detail page with install copy button and star/report controls)
OPTIONS <endpoint> for browser preflight (CORS)

GET /servers and GET /servers/<name> responses include:

maintainerVerified + badges
qualityScore
readmeUrl
permissionsSummary
installCommandCopy

Client integration:

berth link <client> [--watch]
berth unlink <client>

Supported clients:

claude-desktop
cursor
windsurf
continue
vscode

For complete argument details, use:

berth --help
berth <command> --help

Registry source overrides (advanced):

BERTH_REGISTRY_INDEX_URL (remote JSON index)
BERTH_REGISTRY_INDEX_FILE (local JSON index file)
BERTH_REGISTRY_CACHE (cache file path)

Security Model

Berth enforces permission-aware runtime behavior with explicit local overrides.

Permission Categories

environment variables (env:*)
network destinations (network:host:port and wildcards)
filesystem scopes (filesystem:read:/path, filesystem:write:/path)
executable allowlist (exec:<command>)

Commands

Inspect and manage permissions:

berth permissions github
berth permissions github --grant env:GITHUB_TOKEN
berth permissions github --revoke network:*
berth permissions github --reset
berth permissions github --export

Audit runtime actions:

berth audit
berth audit github --since 24h
berth audit github --action start
berth audit github --json
berth audit github --export audit.jsonl

Enforcement Notes

launch and link flows apply effective env permissions
full network revocation blocks launch/proxy and is recorded in audit
undeclared network grants emit a warning and audit event (permission-network-warning)
org policy denials are enforced at launch/restart/proxy, status-triggered recovery, and background supervisor auto-restart paths, and are recorded as policy-denied for launch/proxy/auto-restart denials
client linking skips servers denied by org policy and prints a warning
berth.sandbox=basic uses backend hardening (landlock-restrict + setpriv on Linux when available, generated sandbox-exec profile on macOS, Job Objects on Windows)
berth config <server> --set key=value --secure stores sensitive values in OS keyring (macOS Keychain / Linux secret-tool) or AES-256-GCM encrypted file backend
proxy sessions enforce exec-permission filtering — tool calls not in the allowed set receive a JSON-RPC error and a tool-call-denied audit event is recorded
resource limits (berth.max-memory, berth.max-file-descriptors) are enforced via setrlimit on Unix
audit data is stored as JSONL for deterministic parsing

Org policy file (~/.berth/policy.toml) supports:

server deny list via [servers].deny
wildcard/write restrictions via [permissions]:
- deny_network_wildcard
- deny_env_wildcard
- deny_filesystem_write
- deny_exec_wildcard

Behavior Examples

1. Revoke secret exposure

berth permissions github --revoke env:GITHUB_TOKEN
berth start github

Expected behavior: process can launch, but GITHUB_TOKEN is filtered out from the runtime env map.

2. Block all network access

berth config github --set berth.sandbox=basic
berth config github --set berth.sandbox-network=deny-all
berth start github

Expected behavior: launch is blocked with exit code 1, and a denial event is written to the audit log.

3. Export auditable events

berth audit github --since 24h --json --export audit.json

Expected behavior: matching events are exported as a JSON array for machine review.

4. Enforce org-level deny rules

[servers]
deny = ["github"]

[permissions]
deny_network_wildcard = true
deny_env_wildcard = true
deny_filesystem_write = true
deny_exec_wildcard = true

berth start github

Expected behavior: launch is blocked by policy and a policy-denied event is written to audit.

5. Keep blocked servers out of client configs

berth link claude-desktop

Expected behavior: servers denied in ~/.berth/policy.toml are excluded from generated mcpServers entries.

Runtime Operations

Berth manages server processes through a local runtime state model.

Lifecycle

berth start github
berth stop github
berth restart github

Stop behavior is graceful-first: Berth sends a normal termination signal, waits briefly for exit, and escalates to force termination only when needed.

Status and Logs

berth status
berth status --health-check
berth logs github --tail 100

Status includes process state and, when available, PID and memory metadata.

The --health-check flag adds an MCP protocol health probe column: Berth sends a JSON-RPC initialize request to each running server and reports the protocol version and server name.

Auto-Restart Policy

Config keys:

berth.auto-restart (true / false)
berth.max-restarts (positive integer)
berth.sandbox (basic / off)
berth.sandbox-network (inherit / deny-all)
berth.max-memory (memory limit with K/M/G suffix, e.g. 512M, 1G)
berth.max-file-descriptors (positive integer, e.g. 1024)

When auto-restart is enabled, Berth launches a hidden tokio-backed supervisor process that monitors crash exits and performs bounded restarts without requiring berth status polling.

When sandbox mode is enabled:

Linux uses landlock-restrict for filesystem scope enforcement when available and setpriv --no-new-privs for additional hardening
macOS uses sandbox-exec with a generated profile and declared write-path allowances
Windows uses Job Objects for process isolation
Other platforms fall back to standard process launch while preserving policy config

Global Configuration

Berth supports a global config file at ~/.berth/berth.toml that provides workspace-wide defaults:

[runtime]
auto_restart = true
max_restarts = 5

[security]
sandbox = "basic"
sandbox_network = "inherit"

Per-server config values override global defaults. A missing or malformed global config file is silently ignored.

Example:

berth config github --set berth.auto-restart=true
berth config github --set berth.max-restarts=3
berth config github --set berth.sandbox=basic
berth config github --set berth.sandbox-network=inherit

Client Integration

Berth can write MCP client configuration entries for installed servers.

Supported Clients

Claude Desktop (claude-desktop)
Cursor (cursor)
Windsurf (windsurf)
Continue (continue)
VS Code (vscode)

Commands

berth link claude-desktop
berth link cursor
berth link windsurf
berth link continue
berth link vscode

berth unlink claude-desktop

Watch Mode

Use --watch to keep the client config in sync as servers are installed or removed:

berth link claude-desktop --watch

Berth polls the servers directory every 2 seconds and re-generates the client config when changes are detected. Press Ctrl+C to stop.

Behavior

validates required server config before linking
writes/updates the client MCP config file
creates a backup before modifying existing client config
applies env permission filtering to linked server entries

Team Workflows

Use config bundles to share reproducible local setup across a team.

Export

berth config export team-berth.toml

Import

berth config import team-berth.toml

Suggested Flow

team lead prepares baseline server installs and config values
team lead exports bundle and shares it through internal channels
teammates import bundle and run berth start
each developer sets personal secrets locally as needed

Keyboard shortcuts

Berth Documentation