@sonoma-security/mcp-gateway

Local MCP gateway for tool-level visibility and policy enforcement. Intercepts MCP tool calls, reports telemetry to Sonoma, and enforces allowlist/blocklist policies.

Quick Start

Add to your MCP client config (~/.cursor/mcp.json, Claude Desktop, etc.):

{
  "mcpServers": {
    "sonoma": {
      "command": "npx",
      "args": ["@sonoma-security/mcp-gateway@latest"],
      "servers": {
        "filesystem": {
          "command": "npx",
          "args": ["@modelcontextprotocol/server-filesystem", "/tmp"]
        }
      }
    }
  }
}

On first run, the gateway prompts for OAuth login. That's it - tool calls are now visible in your Sonoma dashboard.

How It Works

AI Client (stdio) -> Sonoma Gateway -> [Upstream MCP Servers]
                           |
                           +-> Telemetry to Sonoma
                           +-> Policy enforcement

The gateway:

1. Spawns your upstream MCP servers
2. Aggregates tools (namespaced as serverName__toolName)
3. Forwards tool calls to the appropriate server
4. Reports telemetry (tool name, duration, status)
5. Blocks tools per your org's allowlist/blocklist

Auto-Detection

By default (no arguments), the gateway auto-detects config from:

• ~/.claude.json (Claude Code)
• ~/.cursor/mcp.json (Cursor)
• ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop)
• ~/.codeium/windsurf/mcp_config.json (Windsurf)

Non-Standard Config Location

If your config is elsewhere, pass --mcp-json-path:

{
  "mcpServers": {
    "sonoma": {
      "command": "npx",
      "args": ["@sonoma-security/mcp-gateway@latest", "--mcp-json-path", "/custom/path/mcp.json"],
      "servers": { ... }
    }
  }
}

Auth Modes

User ID (default)

Opens browser for OAuth on first run. Tool calls attributed to logged-in user.

Org Key

Device-level telemetry via API key. No login required.

"env": {
  "SONOMA_API_KEY": "org_xxx_yyy",
  "SONOMA_GATEWAY_AUTH_MODE": "org_key"
}

CLI

npx @sonoma-security/mcp-gateway@latest --help

# Auth commands
npx @sonoma-security/mcp-gateway@latest --login   # OAuth login
npx @sonoma-security/mcp-gateway@latest --logout  # Clear credentials
npx @sonoma-security/mcp-gateway@latest --status  # Show auth status

# Debug mode
npx @sonoma-security/mcp-gateway@latest --debug

Environment Variables

| Variable | Description | |----------|-------------| | SONOMA_ENDPOINT | Sonoma API URL (default: https://app.sonoma.dev) | | SONOMA_API_KEY | Org API key (for org_key mode) | | SONOMA_GATEWAY_AUTH_MODE | user_id or org_key |

Limitations

• Stdio servers only - HTTP MCP servers not supported
• Nested config - Servers must be nested under the gateway entry

Development

# Run tests
bun run test

# Typecheck
bun run typecheck

# Test with MCP Inspector
npx @modelcontextprotocol/inspector bun run src/cli.ts --config ./test-config.json --debug

Releasing

Publishing is automated via GitHub Actions with npm trusted publishing (OIDC).

To release a new version:

1. Update version in package.json
2. Commit: git commit -am "chore(mcp-gateway): bump to x.y.z"
3. Tag: git tag mcp-gateway-vX.Y.Z
4. Push both: git push origin staging --tags

CI automatically builds, tests, and publishes to npm. No tokens required.

What's automated: build, test, typecheck, npm publish with provenance What's manual: version bump, git tag, push

License

MIT