Skip to content

Claude Code Reference

How to onboard Claude Code — Anthropic's agentic coding CLI — into Preloop's Safety Layer with the preloop CLI.

Overview

Preloop governs Claude Code on two planes:

  • Tool calls — a managed preloop MCP server entry routes governed tools through the Preloop MCP Firewall, where access rules (allow / deny / require_approval) and approval workflows apply.
  • Model traffic — onboarding can rewrite Claude Code's environment so model calls go through the Preloop Gateway using a managed model alias, giving you cost analytics and budget controls.

Optionally, Preloop can also install a native tool-approval hook so Claude Code's own tool calls (shell commands, file edits) that would normally prompt you in the terminal are routed to Preloop mobile/watch/web approvals instead.

Prerequisites

curl -fsSL https://preloop.ai/install/cli | sh

The installer discovers local agents, walks you through login/signup, and offers to onboard everything it found. See the CLI quickstart for the full flow.

Onboard Claude Code

Step 1: Discover

preloop agents discover

This scans standard configuration paths without mutating anything. For Claude Code it reads ~/.claude/settings.json (primary) or ~/.claude/mcp-servers.json (legacy fallback) and lists any MCP servers already configured there.

Step 2: Onboard

preloop agents onboard "claude code"

Or run preloop agents discover and accept the interactive onboarding prompt. Onboarding:

  1. Creates (or locates) the managed agent identity in your Preloop account and issues a durable credential for it.
  2. Backs up your existing Claude Code config next to the original so you can roll back at any time.
  3. Adds a managed preloop MCP server entry to ~/.claude/settings.json.
  4. Rewrites supported model configuration so Claude Code's Anthropic traffic routes through the Preloop Gateway (sets env.ANTHROPIC_BASE_URL to your Preloop gateway's /anthropic endpoint, env.ANTHROPIC_API_KEY to the managed credential, and pins ANTHROPIC_MODEL to a Preloop model alias).
  5. Runs a live validation prompt through the agent (disable with --skip-live-validate).

Useful flags (see preloop agents onboard --help):

Flag Effect
--dry-run Preview the planned account and config changes without writing anything
--yes / -y Skip confirmation prompts
--all Onboard every discovered agent
--approvals Also install the native tool-permission hook (see below)
--skip-live-validate Skip the post-onboarding live validation prompt
--tags key=value Add key-value tags to the enrolled agent

What gets written

After onboarding, ~/.claude/settings.json contains a managed entry like:

{
  "servers": {
    "preloop": {
      "url": "https://preloop.ai/mcp/v1",
      "transport": "http-streaming",
      "headers": {
        "Authorization": "Bearer <managed credential>"
      }
    }
  }
}

Configuration file location

Preloop treats ~/.claude/settings.json as Claude Code's primary configuration file. ~/.claude/mcp-servers.json is only read as a legacy fallback when settings.json is absent.

Step 3: Verify

preloop agents status "claude code"     # local + remote enrollment state
preloop agents validate "claude code"   # config validation
preloop agents validate "claude code" --live  # plus a live prompt through the agent
preloop agents list                     # all managed agents in your account

You can also open https://preloop.ai/console/agents — Claude Code appears as a card with its onboarding state (Fully onboarded, MCP only, Gateway only, or Discovered).

Native tool approvals (PreToolUse hook)

Claude Code has powerful native tools (shell, file edits) that never pass through an MCP server. To govern those too, onboard with:

preloop agents onboard "claude code" --approvals

(Interactive onboarding also offers this as a Route Claude Code's native tool calls ... through Preloop approvals? prompt.)

This installs a PreToolUse hook entry in ~/.claude/settings.json that runs preloop agents permission-hook --source claude_code before each tool call, plus a per-agent credential under ~/.preloop/agents/. Because Claude Code's PreToolUse fires on every tool call, the hook first evaluates your own Claude Code permission settings and only escalates calls that would have prompted you — those become Preloop approval requests you can answer from the mobile apps, watch, or web console. Calls your own config already allows proceed untouched.

Using governed tools

Once onboarded, tools exposed through the managed preloop MCP server are subject to your account's access rules and approval workflows. When Claude Code invokes a tool that requires approval, the call blocks until you approve or deny it (dashboard, email, or mobile), then the result is returned to the agent as usual.

Multi-step workflows behave the same way: each governed tool call in the sequence creates its own approval request as your rules dictate.

The always-available request_approval tool lets the agent explicitly ask for human sign-off with custom context — see Built-in Tools.

Rollback and offboarding

Onboarding always backs up the original config, so you can undo everything:

preloop agents restore "claude code"    # restore the most recent local backup
preloop agents offboard "claude code"   # restore config and remove managed enrollment

offboard also removes the approvals hook and its credential if they were installed, and can optionally clean up the managed model and MCP servers in your account (--remove-model, --remove-mcp-servers).