Claude Code Hooks: Automate Your Agent Workflow

The short answer

Claude Code hooks are event-driven automations that run before or after agent actions, at session boundaries, and at other lifecycle events. Today they can inspect or block MCP tool calls, invoke an already connected MCP tool, run commands, or call HTTP endpoints—but they do not replace an MCP server or make one portable across clients.

Table of contents

This guide covers the mechanism, a verified setup, client differences, failure modes, and the first MCP connections worth making.

• How Claude Code hooks work today
• Step-by-step setup
• Claude Code vs other MCP clients
• The catch most guides skip
• What to connect first
• Our verdict

How Claude Code hooks work today

Hooks are deterministic rules around Claude Code’s agent loop: an event fires, a matcher selects relevant events, and a handler runs. MCP connects Claude Code to outside systems; hooks decide what happens around those connections.

The official hooks reference documents events including PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, SessionStart, and Stop. A handler can be a command, HTTP request, prompt, agent, or mcp_tool. Command hooks receive JSON on standard input with common and event-specific fields.

MCP tools appear in tool events under the documented pattern mcp__<server>__<tool>. A regular-expression matcher such as mcp__.*__write.* can target write-named tools across connected servers. Conversely, an mcp_tool handler triggers a specific tool on a connected server, so it requires the real server key, tool name, and input schema.

This separation is the design’s best feature. MCP gives the model optional capabilities; hooks provide repeatable checks, logs, notifications, or blocks. For general installation, start with our guide to adding an MCP server, then add hooks only where an event needs policy or automation.

Step-by-step setup

Start with an observable PostToolUse hook, prove that matching works, and only then add a blocking PreToolUse policy. This keeps a typo from stopping legitimate work.

1. Choose the correct scope. Put a personal experiment in .claude/settings.local.json, a team rule in .claude/settings.json, or a cross-project rule in ~/.claude/settings.json. There is no standalone .claude/hooks.json; Anthropic’s configuration troubleshooting guide calls that out as a common failure.

2. Create the hook script. Save this as .claude/hooks/log-mcp.sh. It records only the event and tool name, avoiding full tool inputs in the log.

#!/bin/sh
mkdir -p .claude/logs
jq -c '{event: .hook_event_name, tool: .tool_name}' \
  >> .claude/logs/mcp-tools.jsonl

On macOS or Linux, run chmod +x .claude/hooks/log-mcp.sh. The official examples also use jq; install it first or use an approved parser.

3. Register the hook. Add this documented structure to the chosen settings file. Merge the hooks property if the file already contains settings.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "mcp__.*",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/log-mcp.sh",
            "args": [],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

${CLAUDE_PROJECT_DIR} is an official path placeholder, and exec-form args avoids shell-splitting paths with spaces. See Anthropic’s path-handling guidance.

4. Connect and verify an MCP server separately. Use the vendor’s exact instructions or browse MCP Directory’s best MCP servers. claude mcp list reports health, /mcp handles status and OAuth, and project-shared servers live in .mcp.json, according to the Claude Code MCP guide.

5. Test with a harmless read. Open /hooks and confirm the source, event, matcher, and command. Perform a read-only MCP action, then inspect .claude/logs/mcp-tools.jsonl. If no line appears, check the actual tool name before changing the matcher.

6. Promote enforcement carefully. A PreToolUse command can inspect tool_input and return a documented denial or exit with code 2. Keep the test narrow and return a useful reason.