npm package: @nano-step/shared-mcp-proxy
Description: Shared MCP proxy infrastructure - run MCP servers once, share across tools
Latest version: 1.4.4

# 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):

```bash
npx @nano-step/shared-mcp-proxy
```

Or use individual commands:

```bash
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

```bash
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.

```bash
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:

```bash
./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`:
   ```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`:
   ```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:

```bash
./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
```