@nano-step/shared-mcp-proxy

shared-mcp-proxy

Shared MCP proxy infrastructure that runs MCP servers once on the host machine and exposes them via SSE to multiple Docker containers and AI CLI tools. Eliminates memory-wasteful duplication (N containers × M CLIs × K MCPs).

Architecture

• mcp-proxy runs on host (port 9902), manages stdio MCP servers
• Containers connect via SSE over host.docker.internal:9902
• nano-brain runs separately on host (port 3100)
• playwright stays container-local (needs container Chromium)
• Memory savings: ~3.4GB → ~330MB for typical setup (3 containers × 2 CLIs × 4 MCPs)

Quick Start

One command does everything (install + generate configs + start proxy):

npx @nano-step/shared-mcp-proxy

Or use individual commands:

npx @nano-step/shared-mcp-proxy install    # Install mcp-proxy + MCP packages
npx @nano-step/shared-mcp-proxy generate   # Generate configs for all tools
npx @nano-step/shared-mcp-proxy start      # Start mcp-proxy (auto-restarts on crash)
npx @nano-step/shared-mcp-proxy stop       # Stop mcp-proxy
npx @nano-step/shared-mcp-proxy status     # Check status + per-process memory usage
npx @nano-step/shared-mcp-proxy restart    # Restart after config changes

Server Management

npx @nano-step/shared-mcp-proxy list              # List all servers with enabled/disabled status
npx @nano-step/shared-mcp-proxy enable <name>     # Enable a server
npx @nano-step/shared-mcp-proxy disable <name>    # Disable a server

Logging

Debug logging is off by default. Enable it to see all MCP requests flowing through the proxy.

npx @nano-step/shared-mcp-proxy logs --enable     # Turn on debug logging
npx @nano-step/shared-mcp-proxy restart            # Apply the change
npx @nano-step/shared-mcp-proxy logs               # Tail the log (Ctrl+C to stop)
npx @nano-step/shared-mcp-proxy logs --status      # Check logging status + log file size
npx @nano-step/shared-mcp-proxy logs --disable     # Turn off (warnings only)
npx @nano-step/shared-mcp-proxy logs --clear       # Clear the log file

Or run the bash scripts directly:

./install.sh && ./generate.sh && ./start.sh

MCP Servers

Server	Location	Description
Sequential-Thinking	host	Dynamic problem-solving through chain-of-thought reasoning
graphql-tools	host	GraphQL schema inspection and query execution
database-inspector	host	Database schema exploration and query tools
playwright	container	Browser automation (requires container Chromium)
nano-brain	external	Persistent memory and code intelligence (port 3100)
linear	host	Linear issue tracking integration
amplitude	host	Amplitude analytics integration
figma	host	Figma design file inspection

Supported Tools

Tool	Format	Config File	Top Key
opencode	opencode	config/opencode.mcp.json	mcp
amp	amp	config/amp.mcp.json	mcpServers
claude	claude	config/claude.mcp.json	mcpServers
gemini	gemini	config/gemini.mcp.json	mcpServers
codex	codex	config/codex.mcp.toml	mcp_servers
qwen	qwen	config/qwen.mcp.json	mcpServers
vscode	vscode	config/vscode.mcp.json	servers
cline	cline	config/cline.mcp.json	mcpServers
roocode	roocode	config/roocode.mcp.json	mcpServers
antigravity	antigravity	config/antigravity.mcp.json	mcpServers

Configuration

• mcp-config.json — master config, edit this to add/remove servers or tools
• generate.sh — regenerate after editing mcp-config.json
• Each server has "enabled": true/false to toggle without removing
• Each server has "tools": [...] array to control which tools see it
• Environment variables for secrets: set LINEAR_API_KEY, AMPLITUDE_API_KEY, AMPLITUDE_SECRET_KEY, FIGMA_API_KEY on host before starting mcp-proxy

Adding a New MCP Server

• Add server entry to servers section in mcp-config.json:

  "my-server": {
    "command": "my-mcp-server",
    "args": [],
    "env": {},
    "location": "host",
    "tools": ["opencode", "amp", "claude"],
    "enabled": true
  }
  

• If the server needs a new npm package, add install command to install.sh
• Run ./generate.sh to regenerate all tool configs
• Restart mcp-proxy: ./stop.sh && ./start.sh

Adding a New Tool

• Add tool entry to tools section in mcp-config.json:

  "mytool": {
    "format": "mytool",
    "mcpKey": "mcpServers",
    "defaultPath": "config/mytool.mcp.json"
  }
  

• Add generation block in generate.sh (copy existing tool block and modify)
• Run ./generate.sh to create the config file

Custom Output Paths

Override default config paths with flags:

./generate.sh --opencode-out ~/custom/opencode.json \
              --amp-out ~/custom/amp.json \
              --claude-out ~/custom/claude.json \
              --gemini-out ~/custom/gemini.json \
              --codex-out ~/custom/codex.toml \
              --qwen-out ~/custom/qwen.json \
              --vscode-out ~/custom/vscode.json \
              --cline-out ~/custom/cline.json \
              --roocode-out ~/custom/roocode.json \
              --antigravity-out ~/custom/antigravity.json