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

1. 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
   }

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

Adding a New Tool

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

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

2. Add generation block in generate.sh (copy existing tool block and modify)
3. 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