npm package: @sonoma-security/mcp-gateway
Description: Local MCP gateway for tool-level visibility and enforcement
Author: Sonoma
Latest version: 0.1.13

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

```json
{
  "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`:

```json
{
  "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.

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

## CLI

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

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