Enterprise MCP Gateway install

The fleet-deployment path for the AgentKeeper MCP Gateway. Written for IT and platform teams rolling the gateway out to 10+ workstations through a configuration-management or native package tool. If you are an individual developer trying the gateway on your own machine, use the one-line install instead.

Choose the managed path

The remainder of this page covers standalone and Windows/macOS provider-wrapper deployment. RPM-managed Linux uses the broker-backed authentication and lifecycle in the Linux Gateway guide instead of the API-key configuration and generic shell recipe below.

Windows and macOS managed routing pause

Do not use Iru/Kandji, Jamf, or Intune to run configure-ide or rewrite native MCP client configs. The managed Gateway artifacts install or upgrade the Gateway binary, write the active user's Gateway config, and remove older Gateway repair LaunchAgents. Claude Desktop, Claude Code, Cursor, Cowork, and project MCP configs remain owned by the client/user.

Use AgentKeeper Claude Code, Cowork, and IDE hooks as the managed protection path while Gateway routing is hardened. If Gateway routing needs explicit validation, run configure-ide --dry-run and configure-ide manually on a test workstation after backing up the user's MCP client config; do not push that step through recurring MDM remediation.

What you finish with

An enterprise rollout is ready when these are true:

1. A specific gateway release and SHA-256 are pinned in your deployment recipe.
2. The active user's ~/.config/agentkeeper-mcp-gateway/config.json is rendered from managed secrets with api_url, api_key, mode, and detection settings.
3. Existing native MCP client configs remain unchanged after every managed install, repair, or recurring check-in.
4. Claude Code, Cowork, and selected IDE/CLI hooks prove live AgentKeeper Activity after restart.
5. Security owns Base Policy MCP server/tool block rules through /gateway/policies or /policies; /gateway/policies is the focused Gateway shortcut.

Rollout sequence

MDM Happy Paths (Windows and macOS)

Every managed path is binary/config-first. The platform-specific wrapper can differ, but the proof sequence is the same: install, config, native MCP config preservation, hook Activity proof, and dashboard verification.

The universal macOS PKG installs the AgentKeeper endpoint runtime. Standalone MCP Gateway is a separate optional assignment. When Gateway is in scope, use the fixed provider wrapper for the pinned Gateway binary and config:

• Iru/Kandji Gateway wrapper
• Jamf Gateway wrapper
• Intune macOS Gateway wrapper
• Intune Windows deployment for the Windows-only builder

Use Install for first-time rollout or missing Gateway installs. Use Repair for already-enrolled machines when you need to upgrade Gateway, refresh managed config, clean older repair LaunchAgents, or re-run binary/config validation.

For Iru/Kandji, do not paste the generic Linux, systemd, or Ansible samples from this page into a Custom Script Library Item. The generated Iru/Kandji script uses the hosted headless wrapper at /mdm/kandji/agentkeeper-mcp-gateway-install.sh, writes the active user's config, preserves native MCP client configs, and removes older repair LaunchAgents.

Manual agentkeeper-mcp-gateway add is not the managed rollout default. Use it only for unsupported config sources, gateway-native servers, labs, CI, or emergency fallback when migration cannot safely parse a customer config.

Standalone Gateway covers MCP traffic launched from supported local client configs. Claude/Cowork native cloud Connectors such as Notion can use separate cloud auth and may not invoke the local Gateway process; treat those as a separate coverage path unless Gateway-side OAuth or the Cowork connector plugin path is installed and proven by mcp.tool_call events.

Design stance

Pin <version, sha256> and fetch directly from GitHub Releases. Do not use the one-line install script in a fleet context. The install script is a convenience UX for interactive developers; the enterprise path is reproducible, versioned, and independently verifiable.

Recipe (generic shell pseudocode)

This standalone recipe is for a customer-owned custom configuration-management path. It is not the Linux Universal RPM recipe.

#!/usr/bin/env bash
set -euo pipefail

# Pin these at rollout time. Rotate by changing both values together.
VERSION="v0.1.17"
SHA256_LINUX_AMD64="<paste from checksums.txt at pin time>"

ARCHIVE="agentkeeper-mcp-gateway_linux_amd64.tar.gz"
BASE="https://github.com/rad-security/agentkeeper-mcp-gateway/releases/download/${VERSION}"

# 1. Download + verify.
curl -fsSLO "${BASE}/${ARCHIVE}"
echo "${SHA256_LINUX_AMD64}  ${ARCHIVE}" | sha256sum -c -

# 2. Install.
tar -xzf "${ARCHIVE}"
install -m 0755 agentkeeper-mcp-gateway /usr/local/bin/agentkeeper-mcp-gateway

# 3. Drop config (rendered from your secret store).
install -d -m 0755 /etc/agentkeeper-mcp-gateway
install -m 0600 -o agentkeeper -g agentkeeper \
  /path/to/rendered/config.json \
  /etc/agentkeeper-mcp-gateway/config.json

The gateway resolves its config from /etc/agentkeeper-mcp-gateway/config.json automatically, no $HOME knowledge required. See the headless install section of the README for the full resolution chain.

Sample config.json

{
  "mode": "audit",
  "api_key": "ak_live_...",
  "api_url": "https://www.agentkeeper.dev",
  "detection": {
    "threat": "warn",
    "sensitive_data": "warn"
  }
}

The api_key can alternatively be supplied via the AGENTKEEPER_API_KEY environment variable (set in the systemd unit, launchd plist, or per-user shell profile). File always wins when set. rotation happens by re-rendering the file from your secret store, not by shadowing it with an env var.

Verifying cosign signatures (optional, one-time per pin)

Every release's checksums.txt is signed by our GitHub Actions workflow via cosign keyless. Verifying once per version bump proves the artifact came from our real build pipeline:

BASE=https://github.com/rad-security/agentkeeper-mcp-gateway/releases/download/${VERSION}
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

Successful verification binds the checksum file to a specific GitHub Actions workflow on a specific tag, the SHA-256 you pin in your recipe is covered by the same signature.

Manual routing validation only

Installing the gateway binary does not route native MCP clients in the current managed rollout. configure-ide remains available for explicit manual validation only; do not invoke it from Iru/Kandji, Jamf, Intune, a login hook, or a recurring repair item.

For manual validation, first back up the user's client config and run:

agentkeeper-mcp-gateway configure-ide --dry-run
agentkeeper-mcp-gateway configure-ide

Treat the write run as a change-managed migration for that workstation. If anything is missing after the dry run, stop and leave native MCP entries untouched. Hooks remain the default managed protection path.

Generic macOS per-user invocation pattern

Managed macOS recipes still resolve the logged-in user so they can write the user's Gateway config with correct ownership. They must not run configure-ide as root or as the console user during the managed rollout. Cowork fleet rollout must use the dedicated provider wrapper with AGENTKEEPER_API_KEY set. Do not run the individual /cowork-install.sh browser-approval path from MDM.

Do not add a configure-ide shell block to managed macOS recipes. If support approves manual routing validation, run the commands interactively with the developer present and keep the backup path in the support record.

The universal macOS PKG does not configure MCP routing or install Cowork. Use the Gateway steps on this page for routing and Cowork setup for Cowork. The Iru/Kandji guide covers only the endpoint runtime PKG.

Discovered but not routed

Use this support sequence only for manual routing validation when /gateway/servers shows Seen only:

1. Run agentkeeper-mcp-gateway configure-ide --dry-run.
2. Verify the server came from a supported config location.
3. Apply agentkeeper-mcp-gateway configure-ide.
4. Fully restart the MCP client.
5. Make a real harmless MCP tool call.
6. Run agentkeeper-mcp-gateway list --health.
7. Check /gateway/servers for Routed, no calls or Active, then check /gateway/activity.

macOS per-user LaunchAgents

Do not deploy a configure-ide LaunchAgent during managed rollout. Current Iru/Kandji, Jamf, and Intune Gateway scripts remove older AgentKeeper Gateway repair LaunchAgents instead of creating new ones.

Claude Code skill and MCP inventory (scan-inventory)

The current Gateway includes a scan-inventory subcommand that captures the skills and MCP servers already installed in each developer's ~/.claude tree and reports them to the dashboard at www.agentkeeper.dev/agents. This is what populates the installed skills and installed MCP servers tables per workstation, the same data the plugin reports, but emitted by the gateway binary instead of requiring a Claude Code plugin install.

agentkeeper-mcp-gateway scan-inventory

What it does:

1. Walks ~/.claude/skills/*/SKILL.md (user-scoped), <cwd>/.claude/skills/*/SKILL.md (project-scoped), and plugin-installed skills via ~/.claude/plugins/installed_plugins.json, with a cache glob fallback if the manifest is missing
2. Reads mcpServers from ~/.claude/settings.json, <cwd>/.claude/settings.json, and <cwd>/.claude/settings.local.json
3. POSTs a payload matching the plugin's format to {api_url}/api/v1/claude-code/checkin

Flags: --dry-run prints the JSON body that would be sent without sending. --cwd <path> overrides the project directory when invoked outside a Claude Code hook. --claude-version <ver> sets the claude_version field when not supplied by the hook envelope on stdin.

Fail-open by design: exits 0 on success, 0 on network failure, non-zero only on a fatal config error. A SessionStart hook that calls this subcommand will never block a developer's Claude Code session.

Wiring into Claude Code SessionStart

The gateway binary replaces the older type: "http" SessionStart hook that POSTed directly to /api/v1/claude-code/checkin. The HTTP hook can't read the filesystem, so it delivered an empty inventory. scan-inventory fixes that.

{
  "hooks": {
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/usr/local/bin/agentkeeper-mcp-gateway scan-inventory",
        "timeout": 30
      }]
    }]
  }
}

For managed endpoint hooks, use the universal runtime package for the operating system. Add scan-inventory only as part of a separately approved Gateway deployment; the Iru/Kandji PKG guide does not configure it.

Standalone Linux per-user systemd routing

The Universal RPM manages per-user routing for enrolled RHEL and Rocky Linux workstations. This standalone pattern applies only to custom Linux deployments outside that RPM lifecycle. Run configure-ide --dry-run first, apply it interactively to the intended workstation, and retain the reported configuration backup path.

Sample systemd unit (Linux)

# /etc/systemd/system/agentkeeper-mcp-gateway.service
[Unit]
Description=AgentKeeper MCP Gateway
After=network-online.target

[Service]
Type=simple
User=agentkeeper
Group=agentkeeper
ExecStart=/usr/local/bin/agentkeeper-mcp-gateway server
Environment=AGENTKEEPER_CONFIG=/etc/agentkeeper-mcp-gateway/config.json
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Sample Ansible task

- name: Install AgentKeeper MCP Gateway
  hosts: developer_laptops
  vars:
    agentkeeper_version: "v0.1.17"
    agentkeeper_sha256_linux_amd64: "<pinned>"
  tasks:
    - name: Download gateway archive
      get_url:
        url: "https://github.com/rad-security/agentkeeper-mcp-gateway/releases/download/{{ agentkeeper_version }}/agentkeeper-mcp-gateway_linux_amd64.tar.gz"
        dest: "/tmp/agentkeeper-mcp-gateway.tar.gz"
        checksum: "sha256:{{ agentkeeper_sha256_linux_amd64 }}"
        mode: "0644"

    - name: Extract gateway binary
      unarchive:
        src: "/tmp/agentkeeper-mcp-gateway.tar.gz"
        dest: "/usr/local/bin/"
        remote_src: yes
        extra_opts: ["--no-same-owner"]

    - name: Render gateway config
      template:
        src: "agentkeeper-config.json.j2"
        dest: "/etc/agentkeeper-mcp-gateway/config.json"
        owner: agentkeeper
        group: agentkeeper
        mode: "0600"
      notify: restart agentkeeper-mcp-gateway

  handlers:
    - name: restart agentkeeper-mcp-gateway
      service:
        name: agentkeeper-mcp-gateway
        state: restarted

Upgrading

Upgrade is the same recipe with a new VERSION + SHA256 pair. The gateway is a single binary with no in-place upgrade path of its own, your config-management tool controls rollout cadence.

Never retag a published version. Every bug fix is a new patch release (v0.1.2, v0.1.3, …). If you already rolled out a version that turned out to be broken, pin forward to the next patch, do not assume a previous pinned SHA-256 will still resolve if we ever had to pull a release.

Private mirrors

If your security review forbids downloading binaries from github.com, mirror the signed release artifacts into an internal package repository and keep the same version, checksum, and signature verification steps. Enterprise customers can also arrange a private AgentKeeper mirror during deployment planning.

Related

• One-line install, for individual developers trying the gateway on their own machine.
• MCP Gateway overview, what the gateway does and how to wire it into your IDE.
• Setup health, for validation and troubleshooting before enforcement.