Skip to main content

Installation

MCP Gateway runs as a shared daemon that all your terminals connect to. There are two ways to run it: HTTP mode (recommended) or NPX wrapper mode.

Performance Note

Always prefer HTTP mode. The NPX wrapper spawns a dedicated bridge process per terminal, which reduces efficiency. HTTP mode gives you true O(1) resource usage.

Run the gateway as a standalone HTTP server. All terminals connect to a single endpoint—no per-terminal overhead.

Step 1: Install the CLI​

# Install globally
npm install -g @hotnsoursoup/mcp-gateway

# Or use npx for one-time setup
npx @hotnsoursoup/mcp-gateway daemon

Step 2: Start the Daemon​

# Start with default settings (port 8989)
mcpg daemon

# Or specify a custom port
mcpg daemon --port 9000

The daemon runs in the foreground. For background operation:

# macOS/Linux
mcpg daemon &

# Or use a process manager like pm2
pm2 start "mcpg daemon" --name mcp-gateway

Step 3: Configure Claude Code​

Add the gateway as an HTTP MCP server. Edit ~/.claude/settings.json:

Without Authentication (localhost only)​

By default, the gateway allows unauthenticated access from localhost:

{
  "mcpServers": {
    "mcp-gateway": {
      "transport": "http",
      "url": "http://localhost:8989/mcp"
    }
  }
}

With Authentication​

For remote access or additional security, enable HTTP authentication and include the token in the headers:

# Generate a token first
mcpg enable-http

# View your token
mcpg show-token

Then configure Claude Code with the headers field:

{
  "mcpServers": {
    "mcp-gateway": {
      "transport": "http",
      "url": "http://localhost:8989/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Replace YOUR_TOKEN_HERE with the token from mcpg show-token.

When to use authentication

Authentication is optional for localhost access but required when exposing the gateway to your network. Enable it for additional security even on localhost if desired.

Step 4: Verify Connection​

# Check gateway status
mcpg status

# Test the endpoint
curl http://localhost:8989/health

Next Steps​