MCP Gateway · node9 documentation

The MCP Gateway is a local stdio proxy that sits between any AI agent and any MCP server. Instead of the agent calling the MCP server directly, every tools/call passes through Node9 first. DLP, smart rules, shields, and your approval flow all apply. The agent never knows Node9 is there; it speaks standard JSON-RPC 2.0 to the gateway.

Agent (MCP client)
  ↓ stdin / stdout (JSON-RPC 2.0)
node9 mcp-gateway          ← intercepts tools/call
  ↓ child stdin / stdout
Upstream MCP server        ← only sees approved calls

The gateway is a transparent pass-through for everything except tools/call and initialize, tools/list, notifications, and all other methods are forwarded unchanged.

Wrap any MCP server by prefixing it with node9 mcp-gateway --upstream:

# Replace an existing server registration
claude mcp add filesystem -- node9 mcp-gateway \
  --upstream "npx -y @modelcontextprotocol/server-filesystem /your/workspace"

# Or add with user scope (available in all projects)
claude mcp add --scope user myserver -- node9 mcp-gateway \
  --upstream "npx -y @modelcontextprotocol/server-myserver"

Check a .mcp.json into the repo so every developer automatically uses the gateway:

{
  "mcpServers": {
    "filesystem": {
      "command": "node9",
      "args": ["mcp-gateway", "--upstream",
               "npx -y @modelcontextprotocol/server-filesystem ."]
    }
  }
}

--upstream takes a single command string. The gateway's tokenizer splits it on whitespace and handles double-quoted paths for filenames with spaces.

MCP tool names differ from Claude Code's built-in tools. Add them to ignoredToolsand toolInspection in ~/.node9/config.json:

{
  "policy": {
    "ignoredTools": ["list_*", "get_*", "read_*"],
    "toolInspection": {
      "bash":          "command",
      "run_command":   "command",
      "execute_shell": "command",
      "query":         "sql"
    }
  }
}

toolInspection maps MCP tool names to the argument field that contains the shell command or SQL query, this lets smart rules inspect run_command the same way they inspect bash.

The same protections that apply to Claude Code hooks apply here, matched against MCP tool names instead of built-in tools:

• DLP: blocks tool calls containing API keys, tokens, or secrets
• Smart rules: regex-based field matching on any tool argument
• Shields: named rule bundles (postgres, filesystem, aws, etc.)
• Approval flow: native popup, browser dashboard, or Slack

When Node9 blocks a tool call, the agent receives a structured JSON-RPC error, not a crash. The agent can read the reason and inform the user:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Node9: Action blocked — Smart Rule 'block-rm-rf-home'.",
    "data": {
      "reason":    "Recursive delete of the home directory is catastrophic",
      "blockedBy": "Smart Rule: block-rm-rf-home"
    }
  }
}

A .mcp.json file from an untrusted repository can specify any --upstream command. Always review .mcp.json before using it, treat it with the same caution as a Makefile or a package.json postinstall script.

• Hooks protect at the AI client level, only for clients that support hooks (Claude Code, Codex, Copilot CLI, Gemini CLI, Antigravity, Hermes)
• Gateway protects at the MCP server level, any client that connects gets protection, with zero hook configuration

Use the gateway when you control the server but not the clients, or when a client has no hook system.