Cursor Hooks: Stacklok MCP Governance

A Cursor hook that restricts MCP (Model Context Protocol) calls to only servers managed by ToolHive, Stacklok's MCP Platform.

Why Stacklok

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 Stacklok's 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 Cursor 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 Cursor's agent attempts to make an MCP call, this hook:

1. Intercepts the call before execution
2. Checks if the target server is managed by ToolHive
3. Optionally validates the server is from the configured ToolHive registry (registry-only mode)
4. Allows approved servers, denies everything else
5. Returns a helpful message to both the user and the agent

Prerequisites

• jq - JSON processor
• ToolHive (thv CLI)

Installation

./install.sh

This will:

1. Copy the hook to ~/.cursor/hooks/
2. Configure ~/.cursor/hooks.json
3. Remind you to restart Cursor

Registry-Only Mode

For enterprise environments that want to restrict MCP servers to only those from the configured ToolHive registry:

./install.sh --registry-only

This blocks custom/local servers that aren't in the registry, even if they're managed by ToolHive. Users attempting to use non-registry servers will see a message directing them to contact their administrator.

Uninstallation

./uninstall.sh

Testing

Run the unit tests (mocks the thv CLI):

./tests/stacklok-hook-test.sh

How it works

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

1. Receives MCP call details as JSON via stdin
2. Extracts the target URL or command
3. Queries thv list to get allowed MCP server URLs
4. Normalizes URLs (handles localhost/127.0.0.1/::1 equivalence)
5. If THV_REGISTRY_ONLY=true, validates the server is from the configured ToolHive registry
6. Returns {"permission": "allow"} or {"permission": "deny", ...}

Configuration

Environment Variable

You can also enable registry-only mode manually by setting the THV_REGISTRY_ONLY environment variable:

THV_REGISTRY_ONLY=true ~/.cursor/hooks/stacklok-hook.sh

Mode	Behavior
Default (THV_REGISTRY_ONLY unset or false)	Allows any ToolHive-managed server
Registry-only (THV_REGISTRY_ONLY=true)	Only allows servers from the configured ToolHive registry