berth-runtime 0.1.1

A safe berth for your AI tools.

Berth is an open-source CLI tool for managing MCP (Model Context Protocol) servers. It lets you discover, install, configure, run, and secure MCP servers from a single interface — replacing manual JSON config editing with a clean developer experience and adding a security/permission layer on top.

Think: Homebrew + Docker + npm — but for MCP servers.

Why Berth?

The MCP ecosystem is growing fast — Anthropic created the protocol, OpenAI adopted it, and hundreds of MCP servers now exist for GitHub, Slack, PostgreSQL, filesystems, search engines, and more. But the developer experience is broken:

• Finding MCP servers is fragmented across GitHub repos, blog posts, and Twitter
• Installing MCP servers means hand-editing JSON config files — one typo breaks everything
• Running MCP servers has no health checks, no auto-restart, no unified logging
• Securing MCP servers is nonexistent — no sandboxing, no permission model, no audit trail

Berth fixes all of this with a single binary.

Install

# Cargo (recommended)
cargo install berth

# npm
npm install -g @berth/cli

# Shell script (latest GitHub release)
curl -fsSL https://raw.githubusercontent.com/berth-mcp/berth/main/install.sh | sh

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

Quick Start

# Search the MCP server registry
berth search github

# Get detailed info about an MCP server
berth info github

# List installed MCP servers
berth list

Features

Commands

berth search <query>           Search the MCP server registry
berth info <server>            Show detailed MCP server info
berth list                     List installed MCP servers

berth install <server[@version]> Install an MCP server
berth import-github <owner/repo> Auto-import server from GitHub `berth.toml` (`--ref`, `--manifest-path`, `--dry-run`)
berth uninstall <server>       Remove an MCP server
berth update <server|--all>    Update MCP servers
berth config <server>          Configure an MCP server (`--set`, `--secure`, `--env`, or `--interactive`)
berth config export [file]     Export installed server config values as TOML bundle
berth config import <file>     Import server config values from TOML bundle

berth start [server]           Start MCP server(s)
berth stop [server]            Stop MCP server(s)
berth restart <server>         Restart an MCP server
berth status [--health-check]   Show MCP server status (state, PID, memory, optional MCP health probe)
berth logs <server>            Show recent MCP server logs

berth permissions <server>     Show/manage/export MCP server permissions (--grant/--revoke/--reset/--export)
berth policy [server]          Show/manage/validate org policy (--init/--set/--json)
berth audit [server]           View/export runtime audit log (supports --since, --action, --json, and --export)
berth analytics [server]       Summarize audit usage and estimated runtime cost (--since, --top, --json)
berth link <client> [--watch]   Link Berth-managed servers to claude-desktop, cursor, windsurf, continue, or vscode
berth unlink <client>          Unlink Berth-managed servers from claude-desktop, cursor, windsurf, continue, or vscode
berth proxy <server>           Run as transparent MCP proxy
berth registry-api             Serve local registry REST API (supports --bind and --max-requests)
berth publish [manifest]       Validate + submit `berth.toml` to local review queue (`--dry-run` available)

Registry API endpoints:

• GET /health
• GET /servers?q=<query>&category=<category>&platform=<platform>&trustLevel=<level>&offset=<n>&limit=<n>&sortBy=<field>&order=<asc|desc>
• GET /servers/suggest?q=<query>&limit=<n>&category=<category>
• GET /servers/facets?q=<query>&category=<category>&platform=<platform>&trustLevel=<level>
• GET /servers/filters
• GET /servers/trending?limit=<n>&category=<category>&platform=<platform>&trustLevel=<level>
• GET /stats?top=<n>
• GET /servers/<name>
• GET /servers/<name>/related?limit=<n>
• GET /servers/<name>/downloads
• GET /servers/<name>/community
• GET /servers/<name>/reports?limit=<n>&offset=<n>
• GET /reports/filters
• GET /reports?server=<name>&reason=<reason>&offset=<n>&limit=<n>
• GET /analytics?server=<name>&since=<duration>&top=<n>
• GET /publish/submissions?status=<status>&server=<name>&offset=<n>&limit=<n>
• GET /publish/submissions/filters
• GET /publish/submissions/<id>
• POST /publish/submissions/<id>/status (JSON body: status, optional note)
• GET /publish/review-events?status=<status>&server=<name>&submission=<id>&offset=<n>&limit=<n>
• GET /publish/review-events/filters
• GET /publishers?maintainer=<name>&verified=<verified|unverified|true|false>&offset=<n>&limit=<n>
• 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 catalog page with q, category, platform, trustLevel, sortBy, order, limit, offset)
• 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 full manifest and quality checks)
• GET /site/servers/<name> (HTML server detail page)
• OPTIONS <any-endpoint> (browser preflight; CORS enabled)

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

• maintainerVerified + badges
• qualityScore (deterministic ranking signal)
• readmeUrl (best-effort repository README link for detail pages)
• permissionsSummary (website-friendly permission counts/flags)
• installCommandCopy (copy-ready install command text)

Permission override formats:

• env:<VAR> (example: env:GITHUB_TOKEN)
• env:*
• network:<host>:<port> (examples: network:api.github.com:443, network:*:443)
• network:*
• filesystem:<read|write>:<path> (examples: filesystem:read:/workspace, filesystem:write:/tmp)
• filesystem:*
• exec:<command> (example: exec:git)
• exec:*

Runtime and sandbox config keys:

• berth.auto-restart (true or false)
• berth.max-restarts (positive integer, default 3)
• berth.sandbox (basic or off)
• berth.sandbox-network (inherit or deny-all)
• berth.max-memory (memory limit, e.g. 512M, 1G)
• berth.max-file-descriptors (file descriptor limit, e.g. 1024)

Sandbox runtime note:

• On Linux, berth.sandbox=basic applies Landlock filesystem restrictions via landlock-restrict when available and also applies setpriv --no-new-privs hardening when available.
• On macOS, berth.sandbox=basic uses sandbox-exec with a generated profile (default-deny baseline, declared write-path allowances).
• On Windows, berth.sandbox=basic uses Job Objects for process isolation.

Global configuration (~/.berth/berth.toml):

• Provides workspace-wide defaults for runtime settings (auto-restart, max-restarts, sandbox)
• Per-server config overrides global defaults
• Missing file or missing keys silently fall back to built-in defaults

Org policy file (optional):

• Path: ~/.berth/policy.toml
• Deny specific servers:
  • [servers]
  • deny = ["github"]
• Deny risky wildcard/write permissions at launch:
  • [permissions]
  • deny_network_wildcard = true
  • deny_env_wildcard = true
  • deny_filesystem_write = true
  • deny_exec_wildcard = true

Registry source overrides (optional):

• BERTH_REGISTRY_INDEX_URL fetch registry JSON via HTTP and use it for lookups.
• BERTH_REGISTRY_INDEX_FILE load registry JSON from a local file path.
• BERTH_REGISTRY_CACHE cache path for downloaded/overridden registry JSON.

Security behavior examples:

• Env secret filtering at launch:
  • berth permissions github --revoke env:GITHUB_TOKEN
  • berth start github (server starts without GITHUB_TOKEN exposed)
• Network hard block:
  • berth config github --set berth.sandbox=basic
  • berth config github --set berth.sandbox-network=deny-all
  • berth start github (blocked with exit code 1)
• Audit export for review:
  • berth audit github --since 24h --json --export audit.json
• Undeclared network override warning (log-only):
  • berth permissions github --grant network:example.com:443
  • berth start github (prints warning and records permission-network-warning)
• Org policy denial:
  • configure ~/.berth/policy.toml with [servers] deny = ["github"]
  • berth start github (blocked and records policy-denied)
  • crash recovery paths (status/supervisor auto-restart) also stay blocked
• Org policy-aware client linking:
  • configure ~/.berth/policy.toml with [servers] deny = ["github"]
  • berth link claude-desktop (skips blocked servers and warns)

Supported MCP Servers (seed registry)

Berth ships with a built-in registry of popular MCP servers:

More MCP servers will be added as the registry grows.

Development

# Prerequisites: Rust 1.75+ and a C linker (gcc/clang)

# Build
cargo build

# Run all tests (unit + integration)
cargo test --workspace

# Run with arguments
cargo run -- search github
cargo run -- info github

# Lint (zero warnings policy)
cargo clippy --workspace --all-targets -- -D warnings

# License/compliance checks
cargo deny check

# Format
cargo fmt --all

# Build documentation site
make docs

# Benchmark regression smoke check (startup median guard)
make bench-smoke

# Run CI quality smoke checks locally
bash scripts/quality-checks.sh

Project Structure

berth/
  Cargo.toml                     # Workspace root
  docs/                          # mdBook documentation source
  crates/
    berth-cli/                   # Binary crate (the `berth` command)
    berth-registry/              # MCP server registry client, types, search engine
    berth-runtime/               # MCP server runtime state management with tokio-backed supervision

Documentation

Full documentation: berth-mcp.github.io/berth

Related

• Model Context Protocol (MCP) — The protocol Berth manages
• MCP Servers — Official MCP server implementations
• Claude Desktop — AI client with MCP support
• Cursor — AI code editor with MCP support
• Continue — Open-source AI coding assistant

License

Apache 2.0