Claude Desktop Proxy

Govern Claude Desktop MCP servers with zero code changes and wrap your claude_desktop_config.json in one command.

thoth is a cross-platform CLI binary that runs as a stdio sidecar between Claude Desktop and any MCP server. Every tools/call passes through the Thoth enforcer before reaching the upstream server — enforcing HIPAA/SOC2 policy, requiring human approval for sensitive operations, and emitting tamper-evident audit evidence.

⚠

Fleet admins: use the deployment runbooks

This page is optimized for single-machine setup and validation. For managed fleet rollout, use Claude Desktop Fleet Configuration with your MDM-specific onboarding: Jamf Onboarding Overview or Intune Onboarding Overview.

✓

No code changes required

The proxy intercepts at the transport layer. Your MCP server, Claude Desktop, and LLM prompt are all unmodified. Governance is transparent to end users.

How it works

Claude Desktop

↓

thoth run (stdio proxy)

local sidecar · low overhead

↓

Thoth Enforcer

ALLOW / BLOCK / STEP_UP

↓

Upstream MCP Server

gdrive, slack, jira, …

The proxy speaks MCP on both sides — it forwards initialize and tools/list transparently, and intercepts every tools/call for policy evaluation before proxying the result back to Claude Desktop.

Endpoint routing contract

Purpose	URL pattern
Control-plane API host	`https://<tenant>.<apex-domain>`
Endpoint proxy policy checks	Derived as `https://enforce.<tenant>.<apex-domain>`
Endpoint registration + check-ins	Derived automatically as `https://grid.<tenant>.<apex-domain>`

For endpoint proxy traffic, enforcer_url and govapi_url are derived from THOTH_TENANT_ID + THOTH_APEX_DOMAIN; users do not need to set separate URL overrides.

Installation

Install thoth

Choose one installation method, then run verification.

ℹ

Current stable release

As of June 8, 2026, the current stable binary line is thoth/v0.3.4 (includes both thoth and thothctl).

Method A (recommended): Homebrew tap (macOS admin workstations)

brew tap atensecurity/tap
brew install thoth

thothctl is bundled in the same formula (thoth), so no separate brew install thothctl is required.

Method B (recommended for MDM): notarized PKG (macOS)

# Download thoth-macos-universal.pkg from the matching atensecurity/thoth release
sudo installer -pkg thoth-macos-universal.pkg -target /

Validate installer trust:

pkgutil --check-signature thoth-macos-universal.pkg
spctl --assess --type install --verbose=4 thoth-macos-universal.pkg

Method C: manual binary install (GitHub Releases)

VERSION="0.3.4" # update when a newer stable thoth/v* release is published
curl -fsSL -o thoth-macos-universal \
  "https://github.com/atensecurity/thoth/releases/download/v${VERSION}/thoth-macos-universal"
curl -fsSL -o checksums.sha256 \
  "https://github.com/atensecurity/thoth/releases/download/v${VERSION}/checksums.sha256"
grep "thoth-macos-universal" checksums.sha256 | shasum -a 256 -c -
chmod +x thoth-macos-universal
sudo mv thoth-macos-universal /usr/local/bin/thoth

Use the platform-matching asset from the same release: thoth-macos-universal, thoth-linux-x86_64, thoth-linux-arm64, or thoth-windows-x86_64.exe. On Windows, download thoth-windows-x86_64.exe and place it on your PATH.

The proxy is distributed as a native binary (not a pip package).

Enterprise release verification assets are published for each thoth/v* release: checksums.sha256, Sigstore bundles (*.sigstore.json), SBOMs (sbom.cdx.json, sbom.spdx.json), provenance.json, and santa-metadata.json.

Verify installation

thoth --version
thoth doctor
thoth health --json

Keep the binary current

thoth update

Alias and force reinstall options:

thoth self-update
thoth update --force

✓

Release channel mapping

MCP proxy and CLI releases use thoth/v* tags. SDK releases use sdk/go/v*, sdk/python/v*, and sdk/npm/v*.

First run also bootstraps a local profile at ~/.thoth (Linux/macOS/Windows):

~/.thoth/intent_map.json
~/.thoth/sessions/<tenant>--<govapi-host>--admin-token.jwt (after thothctl auth login)
~/.thoth/proxy_api_key.json

The proxy tightens ~/.thoth/proxy_api_key.json file permissions to 0600 where supported.

Set endpoint identity and tenant defaults

Set these identity values per endpoint/user session:

export THOTH_TENANT_ID="your-org"
export THOTH_USER_ID="you@company.com"

Endpoint identity is auto-resolved by proxy in this order:

Managed device ID override (THOTH_INTUNE_DEVICE_ID / INTUNE_DEVICE_ID / THOTH_JAMF_COMPUTER_ID / JAMF_COMPUTER_ID)
OS machine identity
Hostname fallback (HOSTNAME / hostname)

Optional:

export THOTH_APEX_DOMAIN="<apex-domain>"
export THOTH_ENV="prod"                   # default

When THOTH_TENANT_ID is set, the proxy derives fleet registration URL automatically:

https://grid.<tenant>.<apex-domain>/v1/endpoints/register

Sign in with SSO (recommended)

Use thothctl to create a tenant-scoped local session token, then run the proxy with that bearer session:

thothctl auth login --tenant-id "$THOTH_TENANT_ID" --admin-email "$THOTH_USER_ID"

Equivalent wrapper command:

thoth auth login --tenant-id "$THOTH_TENANT_ID" --admin-email "$THOTH_USER_ID"

API key fallback is still supported for break-glass automation:

thoth set-api-key --api-key "aten_thoth_agent_prod_fallback_key_here"

Wrap your Claude Desktop config

thoth wrap-config transforms your existing claude_desktop_config.json — adding the proxy in front of each MCP server without removing any of your current configuration.

thoth wrap-config \
  --tenant-id "$THOTH_TENANT_ID" \
  --enforcement-mode block \
  --env THOTH_USER_ID="$THOTH_USER_ID" \
  --env THOTH_APEX_DOMAIN="${THOTH_APEX_DOMAIN:-<apex-domain>}" \
  --output ~/Library/Application\ Support/Claude/claude_desktop_config.json \
  ~/Library/Application\ Support/Claude/claude_desktop_config.json

ℹ

wrap-config is idempotent — running it twice on an already-governed config is safe. Already-wrapped servers are only updated when selected values change (for example --env, intent, or enforcement mode).

Restart Claude Desktop

Quit and reopen Claude Desktop. The proxy starts automatically — no user action required.

Verify governance

thoth status

Expected output:

Server     Governed    Agent ID    Session Intent    Enforcement
──────────────────────────────────────────────────────────────
gdrive     ✓           gdrive      —                 block
slack      ✓           slack       —                 block

Servers showing ✓ are governed. Any server without a checkmark is running without Thoth policy.

Manual configuration

If you prefer editing claude_desktop_config.json directly, wrap a server by setting command to thoth and prepending run args:

{
  "mcpServers": {
    "gdrive": {
      "command": "thoth",
      "args": [
        "run",
        "--agent-id",
        "gdrive",
        "--tenant-id",
        "your-org",
        "--enforcement-mode",
        "block",
        "--api-key",
        "aten_thoth_agent_prod_your_key",
        "--",
        "npx",
        "-y",
        "@modelcontextprotocol/server-gdrive"
      ],
      "env": {
        "GDRIVE_CREDENTIALS": "/path/to/creds.json"
      }
    }
  }
}

Everything after -- is passed unchanged to the upstream MCP server.

Session intent (HIPAA minimum-necessary)

For healthcare or regulated workflows, declare a session intent to enforce minimum-necessary access. The enforcer checks every tool call against the allowed tools for that intent before any score-based decisions run.

thoth wrap-config \
  --tenant-id your-tenant-id \
  --intent-map intent_map.json \
  --output governed_config.json \
  base_config.json

intent_map.json maps each server name to its intent:

{
  "gdrive": "calendar_management",
  "slack": "calendar_management",
  "phi-boundary": "phi_eligibility_check"
}

ℹ

HIPAA §164.312(b)

Session intent creates a machine-readable audit record of why each tool was called — satisfying the minimum-necessary documentation requirement for PHI access.

Enforcement modes

👁 observe

Observe

Log all tool calls. Never block or interrupt. Use for baselining agent behavior.

🔐 step_up

Step-Up Auth

Require human approval for out-of-scope calls before execution proceeds.

📈 progressive

Progressive

Escalate automatically: warn → step-up → block after repeated violations.

🛑 block

Block

Immediately reject any tool call outside the approved scope. No exceptions.

Use block as the default for fail-closed enforcement. Use progressive only for phased rollout or baseline learning windows, then move governed servers back to block.

Environment variables

Variable	Required	Description
`THOTH_TENANT_ID`	Yes	Tenant identifier used for governance scope and derived endpoint URLs
`THOTH_USER_ID`	Yes	Per-user identifier for audit trail. Must be a valid email address
`THOTH_FLEET_ID`	Optional	Fleet association used for endpoint registration/check-ins
`THOTH_INTUNE_DEVICE_ID` / `INTUNE_DEVICE_ID`	Optional	Managed-device override for endpoint identity (preferred over hostname)
`THOTH_JAMF_COMPUTER_ID` / `JAMF_COMPUTER_ID`	Optional	Jamf managed-device override for endpoint identity
`THOTH_RUNTIME_BEARER_TOKEN`	Preferred	Runtime bearer token (SSO)
`THOTH_AUTH_TOKEN`	Optional	SSO bearer token alias
`THOTH_AUTH_TOKEN_FILE`	Optional	File containing bearer token or auth session JSON
`THOTH_API_KEY_FILE`	Optional fallback	Path to API key JSON file (`~/.thoth/proxy_api_key.json` auto-default)
`THOTH_API_KEY`	Optional fallback	Direct API key env value
`THOTH_APEX_DOMAIN`	Optional	Apex domain used in derived URLs (set to your tenant domain)
`THOTH_ENV`	Optional	Endpoint environment (`prod` default)
`THOTH_ENDPOINT_CHECKIN_INTERVAL_SEC`	Optional	Endpoint heartbeat interval in seconds (default: `60`)

THOTH_ENFORCER_URL / --enforcer-url are deprecated for proxy runtime and ignored in current releases.

Customer email-domain controls are enforced centrally in Thoth backend tenant policy (admin-managed metadata), not by endpoint-local environment variables.

⚠

Scope mismatch behavior

If a key is valid but endpoint/fleet context does not match exactly, enforcer now allows the request and emits warning logs for investigation. Keep endpoint identity mapping clean in MDM to avoid noisy authorization warnings.

✓

For managed fleets

Keep MDM operational details in one place: Jamf Onboarding Overview and Intune Onboarding Overview. Use Claude Desktop Fleet Configuration for governed config lifecycle, provider sync, and direct manual endpoint enrollment flows.