Claude Code Hooks: ToolHive MCP Governance

A Claude Code plugin that restricts MCP (Model Context Protocol) tool calls to only servers managed by ToolHive.

Why ToolHive

MCP adoption spreads organically: MCP configurations get shared, copied from READMEs, and rarely cleaned up. Security teams lose visibility into what's connected and what data is flowing where causing security risks and compliance headaches.

ToolHive is an open-source platform that brings enterprise-grade security to MCP deployment. It provides a curated registry of approved servers, isolated container runtimes, centralized policy enforcement, and audit logging—without blocking developers from using the tools they need.

This hook is the Claude Code integration. It intercepts every MCP call before execution and verifies the target server is ToolHive-managed. Unauthorized servers are blocked with a clear error message.

What it does

When Claude Code attempts to use an MCP tool, this hook:

1. Intercepts the call before execution (PreToolUse hook)
2. Parses the tool name (mcp__<server>__<tool>) to extract the server name
3. Queries ToolHive (thv list --format json) to get managed servers
4. Fail-closed: If ToolHive is unavailable, denies the call
5. Allows or denies based on plugin mode (see Available Plugins below)
6. Returns structured JSON to Claude Code indicating allow/deny and reason

Available Plugins

This marketplace provides two plugin variants:

Plugin	Description
stacklok-hook	Allows any MCP server managed by ToolHive
stacklok-hook-registry-restricted	Only allows servers from the ToolHive registry

Which plugin should I use?

• stacklok-hook: Use this if you trust all servers your team adds to ToolHive. Any server in thv list is allowed.

• stacklok-hook-registry-restricted: Use this for stricter enterprise environments. Servers must be in ToolHive AND match the ToolHive registry:

  • Container workloads: The server's package must match an image in the registry
  • Remote workloads: The server's remote URL must match a URL in the registry

Supported Platforms

• Linux - Fully supported
• macOS - Supported (requires GNU coreutils)
• Windows - Not currently supported (requires bash shell)

Prerequisites

• Claude Code CLI installed
• jq - JSON processor (brew install jq on macOS)
• GNU coreutils - Required for timeout command (brew install coreutils on macOS). Linux systems typically have this pre-installed.
• ToolHive (thv CLI)

Installation

Option 1: Plugin Marketplace (Recommended)

1. Launch Claude Code in any directory:

   claude

2. Add the marketplace:

   /plugin marketplace add StacklokLabs/stacklok-claude-hooks
   

   If you see an error about marketplace not being found or authentication failed try

   /plugin marketplace add [email protected]:StacklokLabs/stacklok-claude-hooks.git
   

   or

   /plugin marketplace add https://github.com/StacklokLabs/stacklok-claude-hooks
   

3. Install your preferred plugin:

   /plugin install stacklok-hook
   

   Or for registry-restricted mode:

   /plugin install stacklok-hook-registry-restricted
   

4. Select "Install for you (user scope)" when prompted.

5. Exit and restart Claude Code.

Option 2: Manual Installation

1. Clone this repository:

   git clone https://github.com/StacklokLabs/stacklok-claude-hooks.git
   cd stacklok-claude-hooks

2. Start Claude Code with the plugin directory (use absolute path):

   claude --plugin-dir /path/to/stacklok-claude-hooks/plugins/stacklok-hook

   Or for registry-restricted mode:

   claude --plugin-dir /path/to/stacklok-claude-hooks/plugins/stacklok-hook-registry-restricted

3. Restart Claude Code.

Uninstallation

/plugin uninstall stacklok-hook

Or for registry-restricted:

/plugin uninstall stacklok-hook-registry-restricted

Testing

Run the unit tests (mocks the thv CLI):

# Test default mode plugin
./plugins/stacklok-hook/tests/stacklok-hook-test.sh

# Test registry-restricted mode plugin
./plugins/stacklok-hook-registry-restricted/tests/stacklok-hook-test.sh

How it works

The hook (scripts/stacklok-hook.sh):

1. Receives MCP call details as JSON via stdin
2. Extracts tool_name (format: mcp__<server>__<tool>)
3. Parses out the server name
4. Queries thv list --format json to get managed servers
5. For registry-restricted mode: Also checks thv registry list --format json
6. Returns structured JSON:
   • Allow: {"hookSpecificOutput": {"permissionDecision": "allow", ...}}
   • Deny: {"hookSpecificOutput": {"permissionDecision": "deny", ...}, "systemMessage": "..."}

Note that shared functions are in scripts/stacklok-hook-common.sh and sourced by both plugins via symlinks.

Configuration

Debug Logging

Enable debug logs by setting the environment variable:

export THV_HOOK_DEBUG=true

Logs are written to ~/temp_logs/toolhive-hook-bash.log.

Troubleshooting

Hook not triggering

1. Verify the plugin is installed: /plugin list
2. Check that the tool name matches the pattern mcp__.*
3. Restart Claude Code after installation

jq command not found

Install jq:

brew install jq  # macOS
apt install jq   # Ubuntu/Debian

thv command not found

Install ToolHive from: https://github.com/stacklok/toolhive

Permission denied

Make sure the script is executable:

chmod +x ~/.claude/plugins/stacklok-hook/scripts/stacklok-hook.sh

License

Apache 2.0