Claude Desktop Proxy

Govern Claude Desktop MCP servers with zero code changes — install thoth via curl and wrap your claude_desktop_config.json in one command.

thoth is a cross-platform Rust 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)

Rust sidecar · <5ms 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.

Method A (recommended): automated installer (macOS/Linux)

curl -fsSL https://install.atensecurity.com/thoth | sh

Method B: manual binary install (GitHub Releases)

VERSION="0.2.8"
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).

Verify installation

thoth --version
thoth doctor
thoth health --json

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

~/.thoth/intent_map.json
~/.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="atensecurity.com"  # default
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

Get a Thoth API key

Use a key provisioned by your security team, or create one through the control-plane API (POST /:tenant-id/thoth/api-keys).

Recommended: store key material with the built-in helper:

thoth set-api-key --api-key "aten_thoth_agent_prod_your_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 progressive \
  --env THOTH_USER_ID="$THOTH_USER_ID" \
  --env THOTH_APEX_DOMAIN="${THOTH_APEX_DOMAIN:-atensecurity.com}" \
  --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      —                 progressive
slack      ✓           slack       —                 progressive

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", "progressive",
        "--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 progressive for most deployments — it builds a behavioral baseline before escalating to step-up or block. Use block for servers that access PHI or financial data where you want explicit approval on every out-of-scope call.

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_API_KEY_FILE`	Recommended	Path to API key JSON file (`~/.thoth/proxy_api_key.json` auto-default)
`THOTH_API_KEY`	Optional fallback	Direct API key env value (use file-backed secret where possible)
`THOTH_APEX_DOMAIN`	Optional	Apex domain used in derived URLs (default: `atensecurity.com`)
`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.