shack-gateway (Python)

An aggregating MCP server that multiplexes multiple downstream MCP servers behind a single, security-hardened gateway. Speaks JSON-RPC 2.0 over stdio; STDOUT carries only protocol messages and all log output goes to STDERR.

What it does

• Connects to one or more downstream MCP servers at startup and aggregates their tools and resources into a unified namespace (server__tool).
• Exposes a progressive-discovery surface by default: four shack_* meta-tools let clients explore and invoke downstream tools without loading every schema at once. In full mode every downstream tool is exposed directly.
• Runs every tool call through a security pipeline: workspace sandbox (path containment), declarative allow/deny permission rules, and optional pre/post shell hooks.
• Redacts sensitive field names (tokens, secrets, keys, etc.) from log output automatically.

MCP tools

In expose_mode: progressive (the default) only the four meta-tools above appear in tools/list. In expose_mode: full every downstream tool is listed directly.

Configuration

The gateway reads a JSON file (default shack-config.json). All fields except workspace_root are optional.

Permission rule syntax

Rules have the form tool_name(subject_pattern):

• fs__write(*) — match any call to fs__write.
• bash(rm -rf:*) — match calls where the subject starts with rm -rf.
• git(checkout) — exact match on the subject value checkout.

The subject is extracted from the first matching well-known argument key: command, path, file_path, url, query, etc.

Minimal config example:

{
  "workspace_root": "/home/user/project",
  "expose_mode": "progressive",
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
    }
  }
}

Install

python -m venv .venv
source .venv/bin/activate
pip install -e .

Run

shack-gateway --config shack-config.json

The server reads newline-delimited JSON-RPC 2.0 from stdin and writes responses to stdout. Log output goes to stderr.

CLI flags

Usage example

The following shows a complete JSON-RPC 2.0 interaction over stdio. Each request is one line; each response is one line.

Request — list available tools:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"shack_list_tools","arguments":{}}}

Response — compact tool list (empty with no configured downstream servers):

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"tools\":[],\"count\":0}"}]}}

Request — call a downstream tool by namespaced name:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"shack_call_tool","arguments":{"name":"filesystem__read_file","arguments":{"path":"src/main.py"}}}}

Test

pip install pytest
pytest

Unit tests cover config parsing, tool catalog registration and search, permission rule evaluation, sandbox path validation, redaction, and hook invocation. Integration tests in tests/test_proxy.py spawn the gateway process over stdio and exercise the full JSON-RPC surface.