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 — evaluating configured policy, requiring approval when policy returns STEP_UP, and recording decisions for review. This does not establish regulatory conformance.

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. Policy refusals and approval requests remain visible to users.

How it works

Claude Desktop
thoth run (stdio proxy)local sidecar · low overhead
Thoth EnforcerALLOW / BLOCK / STEP_UP
Upstream MCP Servergdrive, 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

Choose and verify the current published binary using the release-channel guide. The binary release includes both thoth and thothctl; SDKs have separate versions.

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

Note

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"
}

Minimum-necessary documentation

Session intent records a machine-readable reason for each tool call. You can use these records as part of your minimum-necessary documentation for PHI access; Thoth does not by itself make a deployment HIPAA compliant.

Enforcement modes

observe

Observe

Collect telemetry without enforcing actions. Python bypasses the enforcer in this mode.

step_up

Step-up auth

Request approval according to server policy. Keep the tool paused until the hold resolves.

progressive

Progressive

Evaluate actions with progressive policy. Outcomes depend on server policy and context.

block

Block

Use blocking enforcement. Server policy decides which actions are permitted or refused.

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.

Next steps

Jamf Onboarding Runbook →Jamf policy sequencing, parameter setup, endpoint health checks, and rollout controls.Intune Onboarding Runbook →Intune config and setup script rollout with per-platform runbooks and Graph automation guidance.Fleet Config Lifecycle →Generate, deploy, and validate governed Claude Desktop config at scale.Enforcement Concepts →Understand ALLOW, BLOCK, STEP_UP, and how progressive mode builds baselines.