Skip to main content

Documentation Index

Fetch the complete documentation index at: https://qwady.wiki/llms.txt

Use this file to discover all available pages before exploring further.

ThornGuard offers two setup paths:
  • Quick setup — mint one activation, then paste a JSON config into your MCP client. No CLI install required.
  • CLI setup — install @thornguard/cli for secure secret storage, profile management, and multi-client config generation. Recommended for production use.

​
Prerequisites

  1. Your ThornGuard license key (starts with THORN-).
  2. The upstream MCP URL you want ThornGuard to protect.
  3. If the upstream server needs its own auth, an upstream bearer token.
  4. A supported MCP client or service entry point. The ThornGuard CLI can generate launcher config for Claude Desktop, VS Code, Cursor, Zed, Windsurf, Cline, and Continue. The manual direct-HTTP path works in clients that can send a remote MCP URL plus custom headers.
If you operate the upstream service yourself, also see Protect Your MCP Server. For platform support details, see Cross-Platform Support.

​
Quick Setup (No CLI Required)

The fastest way to start is pointing your MCP client directly at ThornGuard with custom headers.

​
1. Create an Activation for This Client

Manual setups need one activation per browser, editor, CLI install, or device. Create it first with your primary ThornGuard license key: 
curl -s https://thorns.qwady.app/api/license/activations/ensure \
  -X POST \
  -H "Authorization: Bearer THORN-YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "VS Code on MacBook Pro",
    "meta": {
      "surface": "manual",
      "client": "vscode"
    }
  }'
The response includes two values for that specific client instance:
  • activation_id
  • activation_proof
Store both locally for that client. Do not reuse the same activation proof across multiple machines or editor installs.

​
2. Add the Protected Config

​
Local Bridge Pattern (Claude Desktop Shape)

Use this when your client launches a local command instead of talking directly to a remote HTTP MCP server. The example below uses Claude Desktop’s mcpServers envelope; the inner npx mcp-remote ... command is the part that matters. Add this to your MCP client config (e.g., claude_desktop_config.json): 
{
  "mcpServers": {
    "my-protected-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://thorns.qwady.app/mcp",
        "--header",
        "x-thornguard-license:${THORNGUARD_LICENSE}",
        "--header",
        "x-thornguard-activation-id:${THORNGUARD_ACTIVATION_ID}",
        "--header",
        "x-thornguard-activation-proof:${THORNGUARD_ACTIVATION_PROOF}",
        "--header",
        "x-mcp-target-url:${THORNGUARD_TARGET}"
      ],
      "env": {
        "THORNGUARD_LICENSE": "Bearer THORN-YOUR_KEY_HERE",
        "THORNGUARD_ACTIVATION_ID": "YOUR_ACTIVATION_ID",
        "THORNGUARD_ACTIVATION_PROOF": "YOUR_ACTIVATION_PROOF",
        "THORNGUARD_TARGET": "https://your-mcp-server.com/mcp"
      }
    }
  }
}
If the upstream server requires its own auth token, add another header: 
{
  "mcpServers": {
    "my-protected-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://thorns.qwady.app/mcp",
        "--header",
        "x-thornguard-license:${THORNGUARD_LICENSE}",
        "--header",
        "x-thornguard-activation-id:${THORNGUARD_ACTIVATION_ID}",
        "--header",
        "x-thornguard-activation-proof:${THORNGUARD_ACTIVATION_PROOF}",
        "--header",
        "x-mcp-target-url:${THORNGUARD_TARGET}",
        "--header",
        "x-upstream-auth:${THORNGUARD_UPSTREAM}"
      ],
      "env": {
        "THORNGUARD_LICENSE": "Bearer THORN-YOUR_KEY_HERE",
        "THORNGUARD_ACTIVATION_ID": "YOUR_ACTIVATION_ID",
        "THORNGUARD_ACTIVATION_PROOF": "YOUR_ACTIVATION_PROOF",
        "THORNGUARD_TARGET": "https://your-mcp-server.com/mcp",
        "THORNGUARD_UPSTREAM": "Bearer YOUR_UPSTREAM_TOKEN"
      }
    }
  }
}
If you want the exact launcher shape for Claude Desktop, VS Code, Cursor, or Zed, prefer thornguard print-config --client <client> .... The CLI writes the correct top-level config structure for each supported client.

​
Direct HTTP Pattern (Header-Capable Clients)

If your client supports direct remote MCP connections with custom headers (for example, a header-capable VS Code MCP surface), you can skip mcp-remote: 
{
  "servers": {
    "my-protected-server": {
      "type": "http",
      "url": "https://thorns.qwady.app/mcp",
      "headers": {
        "x-thornguard-license": "Bearer THORN-YOUR_KEY_HERE",
        "x-thornguard-activation-id": "YOUR_ACTIVATION_ID",
        "x-thornguard-activation-proof": "YOUR_ACTIVATION_PROOF",
        "x-mcp-target-url": "https://your-mcp-server.com/mcp"
      }
    }
  }
}
All secrets are in the env block, not visible in the args array. For the manual path, that includes the activation proof as well as the license key. The surrounding JSON envelope differs by client, so verify the outer config shape against your client’s own MCP docs if you are not using the CLI.
The ThornGuard CLI stores secrets in your platform’s native keyring and generates client-specific config without embedding raw tokens.

​
Install

npm install -g @thornguard/cli

​
Fastest Path: thornguard onboard

The interactive wizard handles license storage, profile creation, and verification in one session: 
thornguard onboard
It will prompt for your license key (if not already stored), the upstream MCP URL, transport preference, and auth mode. After saving, it offers to scan your editors for other MCP servers and run doctor to verify the connection.

​
Manual Path

If you prefer step-by-step control, use the individual commands below.

​
Authenticate

thornguard auth login
You’ll be prompted for your license key. It’s stored securely in:
  • macOS: Keychain
  • Linux: freedesktop.org Secret Service (gnome-keyring / KDE Wallet)
  • Windows: DPAPI-encrypted credential file

​
Create a Profile

thornguard profile add github-copilot \
  --display-name "GitHub Copilot (Protected)" \
  --target-url https://api.githubcopilot.com/mcp \
  --upstream-auth-mode bearer \
  --upstream-token-env GITHUB_TOKEN \
  --vendor-name GitHub \
  --repo-url https://github.com/github/github-mcp-server \
  --status-page-url https://www.githubstatus.com \
  --intel-enabled
The CLI stores non-secret profile metadata locally and keeps bearer tokens in the platform keyring. The --display-name flag sets the label shown in your MCP client (spaces and special characters are fine). The internal name (github-copilot) is used for CLI commands.

​
Generate Client Config

Print the config snippet to paste manually: 
thornguard print-config --client claude github-copilot
Or apply it directly to your client’s config file: 
thornguard print-config --client claude github-copilot --apply
The --apply flag merges the profile into the client’s config file, preserving any existing settings. Supported clients: claude, vscode, cursor, zed. The generated config uses a local launcher command — client UIs show the display name, not raw secrets: 
{
  "mcpServers": {
    "GitHub Copilot (Protected)": {
      "command": "thornguard",
      "args": ["run", "github-copilot"]
    }
  }
}

​
Verify the Connection

thornguard doctor github-copilot
If advisory intelligence is enabled, check for warnings: 
thornguard status github-copilot --refresh
See CLI Reference for the full command list and all available options.

​
Already Have MCP Servers Configured?

If you already have MCP servers set up in your client, you can protect them in two commands: 
# Discover all configured MCP servers
thornguard scan

# Interactively protect an unprotected server
thornguard protect
The protect wizard automatically extracts the upstream URL, creates a ThornGuard profile, and rewrites your client config — preserving the original server name with “(Protected)” appended.

​
Verify Your Defenses

Run a quick test to confirm ThornGuard is actively protecting the connection.

​
Test Ingress Protection

Ask your MCP client to send a tool invocation containing:
rm -rf /
Expected: ThornGuard blocks the request and records a BLOCKED_MALICIOUS audit event.

​
Test Egress Redaction

Place a fake secret like AKIAIOSFODNN7EXAMPLE somewhere your upstream MCP server can read, then ask the client to fetch it. Expected: ThornGuard redacts the secret before it reaches the client.

​
Review the Audit Trail

Open the ThornGuard Dashboard and log in with your license key. ThornGuard will create or reuse a browser activation automatically, then you can review telemetry, audit records, and opt-in advisories. For the full request pipeline, see Security Features.