mcp-client

README

smcp

Run MCP servers without blindly trusting them.

---

The problem

Every time you run an MCP server, you're executing arbitrary code with your full system permissions:

uvx some-mcp-server       # What does this code actually do?
npx @someone/mcp-tool     # Can it read your SSH keys? Yes.

No verification. No limits. No sandboxing. No audit trail. For production environments connected to internal databases and APIs, this is an unacceptable risk.

What smcp does

smcp is a drop-in replacement for uvx/npx that adds the security layer they don't have:

1. Verifies every package against its SHA-256 digest before execution
2. Sandboxes processes with CPU, memory, network, and filesystem limits
3. Enforces certification policies (only run code that passed security analysis)
4. Warns LLMs about risky servers by injecting security warnings into the MCP protocol
5. Audits every execution with structured logs and automatic secret redaction

Packages are analyzed upstream by MCP Hub Platform for 14 classes of security vulnerabilities and assigned a certification level (0-3) before they ever reach your machine.

uvx/npx vs smcp

	uvx / npx	smcp
Integrity verification	None	SHA-256 on every artifact
Security analysis	None	14 vulnerability classes, cert levels 0-3
Sandboxing	None (full system access)	CPU, memory, PID, FD limits
Network	Unrestricted	Default-deny (Linux)
Filesystem	Full access	Confined to workdir (Linux)
LLM awareness	None	Injects security warnings into MCP protocol
Secret handling	Visible in env/logs	Automatically redacted
Audit trail	None	Structured JSON logs

---

Install

Ubuntu / Debian (apt)

sudo add-apt-repository ppa:mcphub/smcp
sudo apt update
sudo apt install smcp

Supports Ubuntu Noble (24.04 LTS) and Jammy (22.04 LTS).

Homebrew (macOS)

brew install mcp-hub-corp/tap/smcp

Binary

Download from Releases:

# macOS (Apple Silicon)
curl -sSL -o smcp https://github.com/mcp-hub-corp/mcp-client/releases/latest/download/smcp_*_darwin_arm64.tar.gz
tar xzf smcp_*_darwin_arm64.tar.gz && sudo mv smcp /usr/local/bin/

# macOS (Intel)
curl -sSL -o smcp https://github.com/mcp-hub-corp/mcp-client/releases/latest/download/smcp_*_darwin_amd64.tar.gz
tar xzf smcp_*_darwin_amd64.tar.gz && sudo mv smcp /usr/local/bin/

# Linux (amd64)
curl -sSL -o smcp https://github.com/mcp-hub-corp/mcp-client/releases/latest/download/smcp_*_linux_amd64.tar.gz
tar xzf smcp_*_linux_amd64.tar.gz && sudo mv smcp /usr/local/bin/

# Linux (arm64)
curl -sSL -o smcp https://github.com/mcp-hub-corp/mcp-client/releases/latest/download/smcp_*_linux_arm64.tar.gz
tar xzf smcp_*_linux_arm64.tar.gz && sudo mv smcp /usr/local/bin/

From source

go install github.com/mcp-hub-corp/mcp-client/cmd/smcp@latest

Verify

smcp --version
smcp doctor     # shows which security features your system supports

---

Usage

# Run a certified MCP server
smcp run acme/hello-world@1.2.3

# Run latest version
smcp run acme/tool@latest

# Run by exact digest (immutable)
smcp run acme/tool@sha256:a1b2c3...

# Pre-download for CI/CD
smcp pull acme/tool@1.2.3

# Inspect before running
smcp info acme/tool@1.2.3

# Manage cache
smcp cache ls
smcp cache rm --all

Authentication

smcp login --token YOUR_TOKEN
# or
export MCP_REGISTRY_TOKEN=YOUR_TOKEN

---

Configuration

Create ~/.smcp/config.yaml:

registry_url: "https://registry.mcp-hub.info"
timeout: 5m
max_memory: "512M"
max_cpu: 1000              # millicores (1000 = 1 core)
log_level: "info"

audit_enabled: true
audit_log_file: "~/.smcp/audit.log"

policy:
  min_cert_level: 1        # reject uncertified packages (0-3)
  cert_level_mode: strict  # strict | warn | disabled
  allowed_origins:         # empty = allow all
    - official
    - verified

CLI flags override config. Environment variables use MCP_ prefix (MCP_REGISTRY_URL, MCP_CACHE_DIR, etc.).

---

LLM Security Warnings

When LLMs (Claude Desktop, Cursor, Windsurf) run MCP servers via smcp run --trust, the human user never sees the terminal. smcp solves this by injecting security warnings directly into the MCP protocol for packages with low security scores.

{
  "mcpServers": {
    "data-tool": {
      "command": "smcp",
      "args": ["run", "--trust", "acme/data-tool@latest"]
    }
  }
}

If acme/data-tool scores below 80, smcp intercepts the MCP init handshake and:

1. Prepends a warning to instructions in the initialize response -- the LLM reads it and tells the user
2. Sends a notifications/message with level warning -- some clients show it as a UI banner

After the handshake (3-4 messages), the proxy switches to raw passthrough with zero overhead.

# Custom threshold (default: 80)
smcp run --trust --warning-threshold 60 acme/tool@latest

Config: policy.warning_threshold: 80 in ~/.smcp/config.yaml.

---

Platform support

	Linux	macOS	Windows
Resource limits	cgroups v2	rlimits	Job Objects
Network isolation	namespaces	--	--
Filesystem isolation	Landlock	--	--
Audit logging	full	full	full
Production ready	Yes	No	No

For production with untrusted MCP servers, use Linux or Docker. Run smcp doctor to check your system.

---

Documentation

Architecture	How the pieces fit together
Security model	Threat model and invariants
LLM security warnings	Protocol-level warnings for AI assistants
Examples	Usage patterns and CI/CD integration
Linux sandbox	cgroups, namespaces, Landlock, seccomp
Config reference	All available options
Contributing	Development guidelines

---

License

MIT -- see LICENSE.

---

Part of MCP Hub Platform -- trust infrastructure for MCP servers.