aten-thoth-mcp-proxy 0.1.4

Thoth governance proxy for Claude Desktop / MCP servers

aten-thoth-mcp-proxy

Thoth governance sidecar for Claude Desktop and MCP servers. Intercepts every tools/call and enforces HIPAA/SOC2 policy before the upstream MCP server executes.

Install

pip install aten-thoth-mcp-proxy
thoth --version

On first run, thoth now bootstraps a local profile at ~/.thoth (Linux/macOS/Windows), creates these files if missing:

• ~/.thoth/intent_map.json
• ~/.thoth/proxy_api_key.json (permission tightened to 0600 where supported)

and sets runtime defaults when not already configured:

• THOTH_API_KEY_FILE=~/.thoth/proxy_api_key.json
• THOTH_ENV=prod
• THOTH_ENFORCER_URL=https://enforce.<tenant>.<apex-domain>
• THOTH_GOVAPI_URL=https://grid.<tenant>.<apex-domain>
• THOTH_GOV_API_URL=https://grid.<tenant>.<apex-domain> (legacy alias)

<apex-domain> defaults to aten.security and can be overridden with THOTH_APEX_DOMAIN. You only need to provide tenant/user/endpoint identity: THOTH_TENANT_ID, THOTH_USER_ID, and THOTH_ENDPOINT_ID.

Usage

Wrap a single MCP server

thoth run \
  --agent-id gdrive \
  --tenant-id your-org \
  --enforcement-mode progressive \
  --api-key "$THOTH_API_KEY" \
  -- npx -y @modelcontextprotocol/server-gdrive

Wrap your entire Claude Desktop config (idempotent)

thoth wrap-config \
  --tenant-id your-org \
  --enforcement-mode progressive \
  --output ~/Library/Application\ Support/Claude/claude_desktop_config.json \
  ~/Library/Application\ Support/Claude/claude_desktop_config.json

Deterministic upstream execution (recommended)

For GUI-launched apps (Claude Desktop), prefer explicit executables and PATH over shell-only resolution:

{
  "mcpServers": {
    "filesystem-safe": {
      "command": "thoth",
      "args": [
        "run",
        "--agent-id", "filesystem-safe",
        "--tenant-id", "your-org",
        "--enforcement-mode", "progressive",
        "--",
        "/usr/bin/env",
        "PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/you"
      ]
    }
  }
}

If npx is unavailable, the proxy now attempts a Node package fallback by resolving globally installed MCP packages from npm root -g. If a package is missing, the error includes an actionable command:

npm install -g @modelcontextprotocol/server-filesystem

Show governance state

thoth status

Emit endpoint health for Jamf Smart Groups

thoth health --json

Environment variables

Variable	Description
THOTH_API_KEY	API key from your Thoth dashboard
THOTH_API_KEY_FILE	Path to a file containing API key material (recommended over embedding secrets in args/config)
THOTH_ENFORCER_URL	Override enforcer URL (default: Thoth cloud)
THOTH_ENFORCER_FAILURE_DECISION	Enforcer outage fallback (block, step_up, allow); in staging/prod, allow is ignored unless override is set
THOTH_ENFORCER_ALLOW_FALLBACK_OVERRIDE	Emergency override to allow THOTH_ENFORCER_FAILURE_DECISION=allow in staging/prod
THOTH_USER_ID	Per-user identifier for audit trail (email or LDAP uid)
THOTH_GOVAPI_URL	GovAPI base URL for endpoint registration/check-in
THOTH_GOV_API_URL	Legacy alias for THOTH_GOVAPI_URL (accepted for compatibility)
THOTH_APEX_DOMAIN	Apex domain used for derived defaults (default: aten.security)
THOTH_GOVAPI_BEARER_TOKEN	Optional bearer token for GovAPI auth
THOTH_GOVAPI_API_KEY	Optional API key header for GovAPI auth
THOTH_ENDPOINT_ID	Stable endpoint ID override (defaults to hostname)
THOTH_ENROLLMENT_SOURCE	Enrollment source (jamf, intune, manual, unmanaged)
THOTH_ENV	Endpoint environment (dev, staging, prod)
THOTH_HEARTBEAT_INTERVAL_SECONDS	Heartbeat cadence to GovAPI (default: 60)
THOTH_TLS_VERIFY	Enable strict TLS certificate validation for outbound HTTP (true by default)
THOTH_TLS_CA_BUNDLE	Optional custom CA bundle path used for enforcer/GovAPI TLS validation
THOTH_TLS_PINNED_CERT_SHA256	Optional comma-separated SHA-256 leaf cert fingerprints for certificate pinning (sha256:<hex> or plain 64-char hex)
THOTH_TLS_PIN_CACHE_SECONDS	Certificate pin verification cache TTL in seconds (default: 300)
THOTH_TLS_REQUIRE_AWS_BACKED_CERTS	Require TLS cert trust metadata to be AWS-backed (THOTH_TLS_AWS_ACM_CERT_ARN or THOTH_TLS_AWS_PRIVATE_CA_ARN)
THOTH_TLS_AWS_ACM_CERT_ARN	ACM certificate ARN used for enforcer/GovAPI TLS trust attestation
THOTH_TLS_AWS_PRIVATE_CA_ARN	ACM Private CA ARN used for enforcer/GovAPI TLS trust attestation
THOTH_REQUIRE_NON_ROOT	Require proxy to run as non-root (true by default in staging/prod)
THOTH_EXPECTED_PROXY_USER	Optional expected OS username for proxy runtime validation
THOTH_EXPECTED_PROXY_UID	Optional expected OS uid for proxy runtime validation

Secret handling in wrap-config

By default, thoth wrap-config does not embed --api-key into generated config args. Use environment variables (or THOTH_API_KEY_FILE) at runtime instead.

If you must embed a key for a break-glass scenario, pass --embed-api-key explicitly.

Session intent (HIPAA minimum-necessary)

thoth run \
  --agent-id phi-boundary \
  --tenant-id your-org \
  --session-intent phi_eligibility_check \
  --enforcement-mode block \
  --api-key "$THOTH_API_KEY" \
  -- npx -y @mcp/server-phi-boundary

Enterprise fleet deployment

See Enterprise Fleet Deployment for Jamf + Intune deployment guides.

Why the proxy is open source

The proxy is intentionally open source. Security and compliance buyers — the exact people deploying this — need to audit what runs on their employees' machines. An opaque binary raises questions; readable source closes them.

The moat is not here. The proxy is ~250 lines that intercept a JSON-RPC call and POST to an enforcer. Anyone can write this. What competitors cannot replicate is the enforcer logic, the MOSES behavioral baselines, the compliance packs, and the session telemetry that compounds with every governed customer. All of that is server-side and never ships in this package.

Stable public API

The following are part of the stable public API surface as of v0.1.0. Breaking changes require a major version bump and a migration guide:

Interface	Stable
thoth run CLI flags	✅
thoth wrap-config CLI flags and intent_map.json schema	✅
thoth status output format	✅
--session-intent flag name and string values	✅
THOTH_API_KEY, THOTH_ENFORCER_URL, THOTH_USER_ID env vars	✅
JSON-RPC error codes -32001 (BLOCK) and -32002 (STEP_UP)	✅

The session_intent string values (e.g. phi_eligibility_check, calendar_management) are defined by the enforcer's compliance packs, not this package. New intent values are additive and non-breaking; removing or renaming an existing value is a breaking change on the enforcer side.

License

Apache 2.0