# Claude Desktop Proxy

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

Source: https://docs.atensecurity.com/docs/mcp/proxy

`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](https://docs.atensecurity.com/docs/mcp/fleet-deployment) with your MDM-specific onboarding:
  [Jamf Onboarding Overview](https://docs.atensecurity.com/docs/deployments/jamf-overview) or [Intune
  Onboarding Overview](https://docs.atensecurity.com/docs/deployments/intune-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

Flow: 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

Choose one installation method, then run verification.

**Current stable release:**
  Choose and verify the current published binary using the
  [release-channel guide](https://docs.atensecurity.com/docs/deployments/release-channels). The binary release
  includes both `thoth` and `thothctl`; SDKs have separate versions.

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

```bash
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)

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

Validate installer trust:

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

### Method C: manual binary install (GitHub Releases)

```bash
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

```bash
thoth --version
thoth doctor
thoth health --json
```

### Keep the binary current

```bash
thoth update
```

Alias and force reinstall options:

```bash
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 these identity values per endpoint/user session:

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

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

1. Managed device ID override (`THOTH_INTUNE_DEVICE_ID` / `INTUNE_DEVICE_ID` / `THOTH_JAMF_COMPUTER_ID` / `JAMF_COMPUTER_ID`)
2. OS machine identity
3. Hostname fallback (`HOSTNAME` / `hostname`)

Optional:

```bash
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`

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

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

Equivalent wrapper command:

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

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

```bash
thoth set-api-key --api-key "aten_thoth_agent_prod_fallback_key_here"
```

`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.

**macOS**

```bash
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
```

**Windows**

```powershell
thoth wrap-config `
  --tenant-id $env:THOTH_TENANT_ID `
  --enforcement-mode block `
  --env THOTH_USER_ID=$env:THOTH_USER_ID `
  --env THOTH_APEX_DOMAIN=$env:THOTH_APEX_DOMAIN `
  --output "$env:APPDATA\Claude\claude_desktop_config.json" `
  "$env:APPDATA\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).

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

```bash
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:

```json
{
  "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.

```bash
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:

```json
{
  "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](https://docs.atensecurity.com/docs/deployments/jamf-overview) and [Intune Onboarding
  Overview](https://docs.atensecurity.com/docs/deployments/intune-overview). Use [Claude Desktop Fleet
  Configuration](https://docs.atensecurity.com/docs/mcp/fleet-deployment) for governed config lifecycle,
  provider sync, and direct manual endpoint enrollment flows.

---

## Next steps

- [Jamf Onboarding Runbook →](https://docs.atensecurity.com/docs/deployments/jamf-overview): Jamf policy sequencing, parameter setup, endpoint health checks, and rollout controls.
- [Intune Onboarding Runbook →](https://docs.atensecurity.com/docs/deployments/intune-overview): Intune config and setup script rollout with per-platform runbooks and Graph automation guidance.
- [Fleet Config Lifecycle →](https://docs.atensecurity.com/docs/mcp/fleet-deployment): Generate, deploy, and validate governed Claude Desktop config at scale.
- [Enforcement Concepts →](https://docs.atensecurity.com/docs/getting-started/concepts): Understand ALLOW, BLOCK, STEP_UP, and how progressive mode builds baselines.