Install the MCP Gateway

The developer-convenience install path. One command, any macOS or Linux laptop, signed binary from GitHub Releases.

One-liner

curl -fsSL https://www.agentkeeper.dev/install-gateway.sh | AGENTKEEPER_API_URL=https://www.agentkeeper.dev bash

What this does:

1. Detects your OS and architecture via uname.
2. Downloads the matching release archive from github.com/rad-security/agentkeeper-mcp-gateway/releases/latest.
3. Downloads checksums.txt and verifies the archive's SHA-256 before extraction.
4. Installs agentkeeper-mcp-gateway at /usr/local/bin/ (override with INSTALL_PREFIX).
5. Prompts for an API key and can run post-install setup, unless you skip it.

Prove it worked

Do not stop at a successful install log. A production-ready deployment has to prove the whole path from local Gateway to the dashboard.

If any step fails, open /docs/setup-health#mcp-gateway before tuning policy. Health comes before enforcement.

Supported platforms

Windows binaries are published alongside each release, but this shell script does not install native Windows hosts. Use the Windows Intune/PowerShell path for managed Windows workstations, or download from the releases page and place the .exe on your PATH manually for local testing.

Options

Verifying the signature (optional)

Every release's checksums.txt is signed with cosign keyless via our GitHub Actions workflow. If you want to confirm the checksum file came from our real build pipeline before trusting the SHA-256:

# Install cosign if you don't have it:  brew install cosign  (macOS)
TAG=v0.1.17
BASE=https://github.com/rad-security/agentkeeper-mcp-gateway/releases/download/$TAG
curl -fsSLO "$BASE/checksums.txt"
curl -fsSLO "$BASE/checksums.txt.sig"
curl -fsSLO "$BASE/checksums.txt.pem"

cosign verify-blob \
  --certificate-identity-regexp "https://github.com/rad-security/agentkeeper-mcp-gateway/.github/workflows/release.yml@refs/tags/.*" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --signature checksums.txt.sig \
  --certificate checksums.txt.pem \
  checksums.txt

A Verified OK output means the checksum file was produced by our release workflow, no key material to trust, just the public transparency log.

Troubleshooting

"already exists, re-run with --force to overwrite": You already have a gateway installed. Pass --force if you want to replace it:

curl -fsSL https://www.agentkeeper.dev/install-gateway.sh | AGENTKEEPER_API_URL=https://www.agentkeeper.dev bash -s -- --force

Corporate proxy blocks github.com: The script prints the exact download URL on failure. Fetch manually and extract:

URL=https://github.com/rad-security/agentkeeper-mcp-gateway/releases/latest/download/agentkeeper-mcp-gateway_darwin_arm64.tar.gz
curl -LO "$URL"
tar -xzf agentkeeper-mcp-gateway_darwin_arm64.tar.gz
sudo mv agentkeeper-mcp-gateway /usr/local/bin/

"SHA-256 checksum mismatch": The script refused to install because the downloaded archive does not match the checksums file. Do not override this. Retry on a different network; if the failure persists, open an issue.

Next steps

If you want to run the auth and IDE wiring commands yourself, install the binary with post-install setup disabled:

curl -fsSL https://www.agentkeeper.dev/install-gateway.sh | AGENTKEEPER_API_URL=https://www.agentkeeper.dev AGENTKEEPER_SKIP_SETUP=1 bash

Then run:

These standalone commands are for developer-owned installs. On a workstation enrolled through the Linux Universal RPM, do not run configure-ide directly; use the Linux RPM reconciliation flow so routing and ownership evidence are written atomically.

AGENTKEEPER_API_URL=https://www.agentkeeper.dev agentkeeper-mcp-gateway auth login
agentkeeper-mcp-gateway configure-ide --dry-run
agentkeeper-mcp-gateway configure-ide    # rewrite supported MCP client configs to route through the gateway
agentkeeper-mcp-gateway list --health    # confirm discovery, routing, auth, and next steps

If you use the plain one-liner and paste an API key when prompted, the installer already writes the gateway config and runs configure-ide; in that case restart any MCP-enabled IDE, make one real tool call, and run agentkeeper-mcp-gateway list --health.

configure-ide detects every installed IDE, backs up its existing MCP config, and rewrites it to launch agentkeeper-mcp-gateway server as the Gateway entrypoint during MCP tool use. Any previously-registered servers are migrated into the gateway's own config. Use --dry-run to preview, or --ide=cursor to target a specific IDE. Idempotent: safe to run from a login hook or on every reapply.

See the overview for wiring details per IDE, or Enterprise install for the fleet path.

Manual agentkeeper-mcp-gateway add is not the default setup path. Keep it for unsupported config sources, gateway-native admin setup, or lab cases where there is no supported local MCP client config to migrate.

After verification, use /gateway/policies as the Gateway shortcut for Base Policy MCP server and tool block rules. Use /policies for the full Base Policy workspace, broader runtime profiles, audiences, exceptions, repository scope, and package-safety controls.

For Claude Desktop Chat on macOS or Linux, install Gateway and let configure-ide route every supported local MCP client config:

curl -fsSL https://www.agentkeeper.dev/install-gateway.sh | \
  AGENTKEEPER_API_URL=https://www.agentkeeper.dev \
  AGENTKEEPER_API_KEY=ak_live_REPLACE_ME \
  bash

For Claude Desktop Chat on Windows, install Gateway with the native PowerShell path, then run the per-user configure command:

$ErrorActionPreference='Stop'; $scriptPath=Join-Path $env:TEMP 'agentkeeper-windows-mcp-gateway-install.ps1'; $scriptUri='https://www.agentkeeper.dev/mdm/intune/agentkeeper-windows-mcp-gateway-install.ps1'; for($i=1;$i -le 5;$i++){try{Invoke-WebRequest -UseBasicParsing $scriptUri -OutFile $scriptPath -TimeoutSec 60; break}catch{if($i -eq 5){throw}; Start-Sleep -Seconds ([Math]::Min(($i * 2),10))}}; $nativePowerShell=if($env:PROCESSOR_ARCHITEW6432){Join-Path $env:WINDIR 'Sysnative\WindowsPowerShell\v1.0\powershell.exe'}else{Join-Path $env:WINDIR 'System32\WindowsPowerShell\v1.0\powershell.exe'}; if(-not (Test-Path $nativePowerShell)){$nativePowerShell='powershell.exe'}; & $nativePowerShell -NoProfile -ExecutionPolicy Bypass -File $scriptPath -AgentKeeperApiUrl 'https://www.agentkeeper.dev' -AgentKeeperApiKey 'ak_live_REPLACE_ME'; if($LASTEXITCODE -ne 0){throw ('AgentKeeper MCP Gateway installer exited with code ' + $LASTEXITCODE)}

& 'C:\Program Files\AgentKeeper\agentkeeper-mcp-gateway.exe' configure-ide

For Claude Desktop / Cowork on macOS or Linux, use the hook installer:

curl -fsSL https://www.agentkeeper.dev/cowork-install.sh | AGENTKEEPER_API_URL=https://www.agentkeeper.dev bash

For Claude Desktop / Cowork on Windows, use the PowerShell installer instead:

$ErrorActionPreference='Stop'; $scriptPath=Join-Path $env:TEMP 'cowork-windows-install.ps1'; $scriptUri='https://www.agentkeeper.dev/cowork-windows-install.ps1'; for($i=1;$i -le 5;$i++){try{Invoke-WebRequest -UseBasicParsing $scriptUri -OutFile $scriptPath -TimeoutSec 60; break}catch{if($i -eq 5){throw}; Start-Sleep -Seconds ([Math]::Min(($i * 2),10))}}; $nativePowerShell=if($env:PROCESSOR_ARCHITEW6432){Join-Path $env:WINDIR 'Sysnative\WindowsPowerShell\v1.0\powershell.exe'}else{Join-Path $env:WINDIR 'System32\WindowsPowerShell\v1.0\powershell.exe'}; if(-not (Test-Path $nativePowerShell)){$nativePowerShell='powershell.exe'}; & $nativePowerShell -NoProfile -ExecutionPolicy Bypass -File $scriptPath -AgentKeeperApiUrl 'https://www.agentkeeper.dev' -AgentKeeperApiKey 'ak_live_REPLACE_ME'; if($LASTEXITCODE -ne 0){throw ('AgentKeeper Cowork helper exited with code ' + $LASTEXITCODE)}

Deploying to a fleet?

This script is a developer-convenience path, not a supply-chain trust anchor. For deploying to a managed fleet (Iru/Kandji, Ansible, Jamf, MDM), use the pinned-version path instead: Enterprise install.