MCP Server URL Allowlist - Claude Code Hook

PreToolUse hook that blocks edits adding remote MCP server URLs unless their host appears in an explicit allowlist, reducing accidental connection to unreviewed OAuth, SSE, or Streamable HTTP MCP endpoints.

by JSONbored·added 2026-06-05·

Claude Code

HarnessClaude Code

Trigger:PreToolUse

Command center

Source

Review first

Review safety and privacy notes before installing or copying commands.

Safety notes Privacy notes

Install & copy

mkdir -p .claude/hooks
cat > .claude/hooks/mcp-server-url-allowlist.sh <<'MCP_SERVER_URL_ALLOWLIST_HOOK'
#!/usr/bin/env bash
set -u

if ! command -v jq >/dev/null 2>&1; then
  exit 0
fi

input=$(cat)
file=$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_input.path // ""')
text=$(printf '%s' "$input" | jq -r '
  def scalar_strings:
    if type == "string" then .
    elif type == "array" then .[] | scalar_strings
    elif type == "object" then .[] | scalar_strings
    else empty end;

  def decoded_config_strings:
    try (fromjson | scalar_strings) catch empty;

  [.tool_input.content, .tool_input.new_string, (.tool_input.edits[]?.new_string)]
  | map(select(type == "string"))
  | .[]
  | ., decoded_config_strings
' 2>/dev/null)
normalized_text=$(printf '%s' "$text" | sed 's#\\/#/#g')

case "$file" in
  *mcp*.json|*.mcp.json|*.claude/settings.json|*/settings.json) ;;
  *) exit 0 ;;
esac

hosts=$(printf '%s' "$normalized_text" | grep -Eo 'https?://[^"[:space:]]+' | awk -F/ '{print $3}' | sort -u)
[ -z "$hosts" ] && exit 0

allowlist=$(printf '%s' "${ALLOWED_MCP_HOSTS:-}" | tr ',' ' ')
for host in $hosts; do
  case " $allowlist " in
    *" $host "*) ;;
    *)
      echo "Blocked remote MCP URL: $host is not in ALLOWED_MCP_HOSTS." >&2
      exit 2
      ;;
  esac
done

exit 0
MCP_SERVER_URL_ALLOWLIST_HOOK
chmod +x .claude/hooks/mcp-server-url-allowlist.sh

Trust & readiness

TrustReview first
Sourcesource-backed
Safety notesPresent
ReviewedNo

Community context

Related entries(4)
Related guides(3)
Community signals

Compare

Integrations & API

Contribute

Suggest a metadata change Claim this listing

Documentation Source repository Browse directory

Review first — review before installing

Open the source and read safety notes before installing.

Citation facts

Source-backed facts for citing this resource, derived directly from the registry — also available as plain text for AI assistants.

Canonical URL: https://heyclau.de/entry/hooks/mcp-server-url-allowlist-hook
Source URLs: https://code.claude.com/docs/en/hooks, https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization
Safety notes: This hook blocks unreviewed remote hosts in MCP-related config edits; it does not prove an allowed host is safe., Run a separate authorization and source review before adding a new host to the allowlist., The hook fails open when jq is unavailable, so CI or pre-commit checks should cover high-assurance environments.
Privacy notes: The hook reads pending config text from Claude Code tool input but does not write files or call the network., Blocked hostnames are printed to stderr and may reveal internal MCP endpoints in the local terminal.
Author: JSONbored
Submitted by: JSONbored
Claim status: unclaimed
Last verified: 2026-06-05

Decision playbook

Review trust signals before you adopt

Signals are present but mixed. Use the checklist below to confirm the source and operational safety for your environment.

Compare context

Selected

Current score

Baseline

—

Delta

No baseline selected

No major trust-signal divergence detected in the current selection.

Source and provenance checks

Needs review

Confirm ownership and provenance before trusting install instructions.

Source link availableRequired
Open the canonical repository and verify ownership.
Done
Source provenance statusRequired
Marked as source-backed.
Done
Metadata reviewed
No reviewed flag detected in metadata.
Pending

Safety and privacy checks

Complete

Validate risk disclosures before installation or API wiring.

Safety notes presentRequired
Review the listed safety guidance before running commands.
Done
Privacy notes presentRequired
Review data handling notes before connecting accounts or secrets.
Done
Trust level risk gateRequired
Trust level does not block evaluation.
Done

Package and install checks

Needs review

Check package metadata and artifact integrity signals.

Install payload available
Install or copy payload is available for review.
Done
Package verification flag
No package verification flag provided.
Pending
Checksum metadata
No checksum provided for downloaded artifact.
Pending

Compare-driven decision checks

Needs review

Use compare context to validate trade-offs before adoption.

Compare tray has multiple entries
Add at least one more entry to compare trust differences.
Pending
Baseline comparison available
No baseline peer selected yet.
Pending
Diverging trust signals identified
No major trust-signal divergence found.
Pending

Setup at a glance

CLI install

Copy-ready — paste the snippet to get started.

Install command

Provided

Config snippet

Provided

Copy snippet

Provided

Prerequisites

3 to clear

Platforms

1 listed

Install type

CLI install

Adoption plan

Balanced adoption plan

Current risk score 24/100. Use staged verification before broader rollout.

Risk 24

Pre-adoption checks

Validate source and review signals before any execution.

Confirm source provenanceRequired
Source URL/provenance metadata is present.
Done
Confirm metadata review state
No review metadata found; increase manual validation.
Pending
Verify install payload
Install/config payload exists and can be inspected.
Done

Security checks

Confirm safety, privacy, and package integrity signals.

Review safety notesRequired
Safety notes are present.
Done
Review privacy notesRequired
Privacy notes are present.
Done
Verify package integrity metadata
No package verification/checksum metadata.
Pending

Rollout

Adopt in controlled steps based on the selected plan.

Run in isolated sandbox firstRequired
Use a constrained sandbox and observe behavior across multiple tasks.
Pending
Roll out graduallyRequired
Roll out to a small cohort before wider usage.
Pending
Set monitoring and fallback
Define rollback path and monitor errors after adoption.
Pending

Evidence readiness

Evidence readiness matrix · balanced

Missing required evidence: Metadata review. Risk score 31.

Risk 31

Source provenance

Present

Source repository/provenance is listed.

Required in this preset

Metadata review

Missing

Review metadata is missing.

Required in this preset

Safety notes

Present

Safety notes are present.

Required in this preset

Privacy notes

Present

Privacy notes are present.

Optional in this preset

Package integrity

Missing

Package integrity metadata is missing.

Optional in this preset

Install payload

Present

Install payload is available.

Required in this preset

Required gaps: Metadata review

Decision timeline

Decision timeline · balanced

Blocking gaps: Check metadata review status. Risk 28.

Risk 28

triage

Confirm source provenanceRequired

Source/provenance metadata is available.

Done

triage

Check metadata review statusRequired

Review metadata is missing.

Pending

verify

Review safety notesRequired

Safety notes are available.

Done

verify

Review privacy notes

Privacy notes are available.

Done

verify

Validate package integrity metadata

Package integrity metadata is missing.

Pending

rollout

Verify install payload and commandsRequired

Install payload is available.

Done

Blockers: Check metadata review status

Prerequisite readiness

3 prerequisites to line up before setup. Includes a review or approval gate.

0/3 ready

Install & runtime1Review & approval1General1

Safety & privacy surface

3 safety and 2 privacy notes across 3 risk areas. Review closely: permissions & scopes, network access.

3 areas

SafetyNetwork accessThis hook blocks unreviewed remote hosts in MCP-related config edits; it does not prove an allowed host is safe.
SafetyPermissions & scopesRun a separate authorization and source review before adding a new host to the allowlist.
SafetyGeneralThe hook fails open when jq is unavailable, so CI or pre-commit checks should cover high-assurance environments.
PrivacyNetwork accessThe hook reads pending config text from Claude Code tool input but does not write files or call the network.
PrivacyNetwork accessBlocked hostnames are printed to stderr and may reveal internal MCP endpoints in the local terminal.

Safety notes

This hook blocks unreviewed remote hosts in MCP-related config edits; it does not prove an allowed host is safe.
Run a separate authorization and source review before adding a new host to the allowlist.
The hook fails open when jq is unavailable, so CI or pre-commit checks should cover high-assurance environments.

Privacy notes

The hook reads pending config text from Claude Code tool input but does not write files or call the network.
Blocked hostnames are printed to stderr and may reveal internal MCP endpoints in the local terminal.

Prerequisites

Claude Code CLI with hooks enabled.
bash, jq, grep, and awk available locally.
ALLOWED_MCP_HOSTS set to a comma-separated list of reviewed remote MCP hosts.

Schema details

Install type: cli
Troubleshooting: No

Source repository stats

Scope: Source repo

Runtime and command metadata

Trigger: PreToolUse
Script language: bash

Script body

#!/usr/bin/env bash
set -u

if ! command -v jq >/dev/null 2>&1; then
  exit 0
fi

input=$(cat)
file=$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_input.path // ""')
text=$(printf '%s' "$input" | jq -r '
  def scalar_strings:
    if type == "string" then .
    elif type == "array" then .[] | scalar_strings
    elif type == "object" then .[] | scalar_strings
    else empty end;

  def decoded_config_strings:
    try (fromjson | scalar_strings) catch empty;

  [.tool_input.content, .tool_input.new_string, (.tool_input.edits[]?.new_string)]
  | map(select(type == "string"))
  | .[]
  | ., decoded_config_strings
' 2>/dev/null)
normalized_text=$(printf '%s' "$text" | sed 's#\\/#/#g')

case "$file" in
  *mcp*.json|*.mcp.json|*.claude/settings.json|*/settings.json) ;;
  *) exit 0 ;;
esac

hosts=$(printf '%s' "$normalized_text" | grep -Eo 'https?://[^"[:space:]]+' | awk -F/ '{print $3}' | sort -u)
[ -z "$hosts" ] && exit 0

allowlist=$(printf '%s' "${ALLOWED_MCP_HOSTS:-}" | tr ',' ' ')
for host in $hosts; do
  case " $allowlist " in
    *" $host "*) ;;
    *)
      echo "Blocked remote MCP URL: $host is not in ALLOWED_MCP_HOSTS." >&2
      exit 2
      ;;
  esac
done

exit 0

Full copyable content

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/mcp-server-url-allowlist.sh"
          }
        ]
      }
    ]
  }
}

About this resource

Features

Watches Write, Edit, and MultiEdit calls before MCP-related config reaches disk.
Extracts HTTP and HTTPS hosts from raw and JSON-decoded pending text.
Blocks hosts not listed in ALLOWED_MCP_HOSTS.
Makes remote MCP additions intentional and reviewable.
Runs locally with bash and jq.

Why use it

Remote MCP servers can sit behind OAuth and expose account data or write-capable tools. This hook adds a small local control: Claude cannot casually paste a new remote endpoint into config unless that host has already been reviewed and added to the local allowlist.

References

Claude Code hooks - https://code.claude.com/docs/en/hooks
MCP authorization specification - https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization

#mcp #hooks #allowlist #security #remote-mcp

Source citations

Source methodology →

Add this badge to your README

Show that MCP Server URL Allowlist - Claude Code Hook is listed on HeyClaude. Paste this Markdown into your README — it renders the badge and links back to this page.

[![Listed on HeyClaude](https://heyclau.de/badge/hooks/mcp-server-url-allowlist-hook.svg)](https://heyclau.de/entry/hooks/mcp-server-url-allowlist-hook)

How it compares

MCP Server URL Allowlist - Claude Code Hook side by side with 3 alternatives on trust, install, platform support, and disclosed safety notes — all from reviewed registry metadata.

1 trust signal differ across this comparison (Submitter).

Field	MCP Server URL Allowlist - Claude Code Hook PreToolUse hook that blocks edits adding remote MCP server URLs unless their host appears in an explicit allowlist, reducing accidental connection to unreviewed OAuth, SSE, or Streamable HTTP MCP endpoints. Open dossier	MCP Config Privacy Scanner - Claude Code Hook PreToolUse hook that reviews proposed writes to MCP configuration files and blocks inline credential values, credential-bearing URLs, and broad filesystem roots before they are saved. Open dossier	Prompt-Injection Content Scanner - Claude Code Hook PreToolUse hook that scans proposed writes to prompt, agent, rule, markdown, and context files for common prompt-injection phrases before the content is saved into an AI-readable surface. Open dossier	Docker Image Security Scanner - Hooks Comprehensive Docker image vulnerability scanning with layer analysis, base image recommendations, and security best practices enforcement. This PostToolUse hook automatically scans Docker images for vulnerabilities when Dockerfiles are modified, providing real-time security validation during development. Open dossier
Next steps	Open dossier API JSON Open LLM Open source Newsletter Claim listing	Open dossier API JSON Open LLM Open source Newsletter Claim listing	Open dossier API JSON Open LLM Open source Newsletter Claim listing	Open dossier API JSON Open LLM Open source Newsletter Claim listing
Trust
Review status	Not reviewed	Not reviewed	Not reviewed	Not reviewed
Package trust	Package not verified	Package not verified	Package not verified	Package not verified
Source provenance	Source-backed	Source-backed	Source-backed	Source-backed
SubmitterDiffers	JSONbored	MkDev11	MkDev11	—
Install risk	Review first	Review first	Review first	Review first
Notes	Safety ✓ Privacy ✓	Safety ✓ Privacy ✓	Safety ✓ Privacy ✓	Safety ✓ Privacy ✓
Brand	—	—	—	Docker
Category	hooks	hooks	hooks	hooks
Source	Source-backed	Source-backed	Source-backed	Source-backed
Author	JSONbored	MkDev11	MkDev11	JSONbored
Added	2026-06-05	2026-06-05	2026-06-05	2025-10-19
Platforms	Claude Code	Claude Code	Claude Code	Claude Code
Harness	Claude Code	Claude Code	Claude Code	Claude Code
Source repo	—	—	—	—
Safety notes	✓This hook blocks unreviewed remote hosts in MCP-related config edits; it does not prove an allowed host is safe. Run a separate authorization and source review before adding a new host to the allowlist. The hook fails open when jq is unavailable, so CI or pre-commit checks should cover high-assurance environments.	✓Runs before Write, Edit, and MultiEdit tool calls and reads only the pending file path plus proposed new text, including replacement fragments for partial edits. Blocks matching MCP configuration edits with exit code 2 when it finds inline credential values, credential-bearing URLs, or broad filesystem roots for filesystem MCP servers. Does not start MCP servers, contact remote MCP endpoints, edit files, delete files, or inspect existing config beyond the proposed tool input. Text and JSON heuristics can miss unusual config shapes or flag reviewed local setups; use `MCP_CONFIG_PRIVACY_ALLOWLIST` only for documented exceptions. Set `MCP_CONFIG_PRIVACY_MODE=advisory` to warn without blocking while a team tunes its MCP policy.	✓Runs before Write, Edit, and MultiEdit calls and reads only the proposed target path plus new text from Claude Code hook input. Blocks with exit code 2 when context-like files contain common instruction-override, disclosure, role-confusion, concealment, or silent tool-execution patterns. Does not send text to a model, call an API, read existing files, start tools, execute generated content, or modify files itself. Pattern matching can miss obfuscated attacks and can flag legitimate security documentation; use advisory mode while tuning the file scope. Set `PROMPT_INJECTION_SCANNER_SCOPE=all` only when the team wants every Write/Edit/MultiEdit payload scanned.	✓Runs automatically on its configured Claude Code hook event and executes shell logic that can read, modify, or delete files in your project (and may run builds, installs, or network calls); review the script and scope it to expected paths before enabling.
Privacy notes	✓The hook reads pending config text from Claude Code tool input but does not write files or call the network. Blocked hostnames are printed to stderr and may reveal internal MCP endpoints in the local terminal.	✓Runs locally and makes no network calls. Does not print credential values, URLs, or full config content; it reports only finding categories. The target file path, finding category, allowlist pattern, and mode variable can still appear in terminal output, Claude Code transcripts, CI logs, or screenshots. Use environment-variable expansion or a secret manager for MCP credentials so private tokens are not committed to project-scoped config files.	✓Runs locally and makes no network calls. Does not print the matched text; it reports only finding categories and generic remediation guidance. The target path, finding categories, mode variable, and allowlist pattern can still appear in terminal output, Claude Code transcripts, CI logs, or screenshots. When documenting prompt-injection examples, quote or redact them so attack text does not become active instruction material in prompt or agent files.	✓Receives Claude Code hook input (session metadata, file paths, and tool output) and reads local project files; review what the script logs or forwards to external services and keep credentials out of its output.
Prerequisites	Claude Code CLI with hooks enabled. bash, jq, grep, and awk available locally. ALLOWED_MCP_HOSTS set to a comma-separated list of reviewed remote MCP hosts.	Claude Code CLI with hooks enabled. bash, jq, grep, sort, and a reviewed `.claude/settings.json` or user-level hook configuration. A team MCP policy for approved servers, credential storage, filesystem scopes, and remote transports.	Claude Code CLI with hooks enabled. bash, jq, grep, sort, tr, and a reviewed `.claude/settings.json` or user-level hook configuration. A team policy for which prompt, rule, agent, documentation, and context files are read as instructions by AI tools.	— none listed
Install	mkdir -p .claude/hooks cat > .claude/hooks/mcp-server-url-allowlist.sh <<'MCP_SERVER_URL_ALLOWLIST_HOOK' #!/usr/bin/env bash set -u if ! command -v jq >/dev/null 2>&1; then exit 0 fi input=$(cat) file=$(printf '%s' "$input" \| jq -r '.tool_input.file_path // .tool_input.path // ""') text=$(printf '%s' "$input" \| jq -r ' def scalar_strings: if type == "string" then . elif type == "array" then .[] \| scalar_strings elif type == "object" then .[] \| scalar_strings else empty end; def decoded_config_strings: try (fromjson \| scalar_strings) catch empty; [.tool_input.content, .tool_input.new_string, (.tool_input.edits[]?.new_string)] \| map(select(type == "string")) \| .[] \| ., decoded_config_strings ' 2>/dev/null) normalized_text=$(printf '%s' "$text" \| sed 's#\\/#/#g') case "$file" in mcp.json\|.mcp.json\|.claude/settings.json\|/settings.json) ;; ) exit 0 ;; esac hosts=$(printf '%s' "$normalized_text" \| grep -Eo 'https?://[^"[:space:]]+' \| awk -F/ '{print $3}' \| sort -u) [ -z "$hosts" ] && exit 0 allowlist=$(printf '%s' "${ALLOWED_MCP_HOSTS:-}" \| tr ',' ' ') for host in $hosts; do case " $allowlist " in " $host ") ;; *) echo "Blocked remote MCP URL: $host is not in ALLOWED_MCP_HOSTS." >&2 exit 2 ;; esac done exit 0 MCP_SERVER_URL_ALLOWLIST_HOOK chmod +x .claude/hooks/mcp-server-url-allowlist.sh	`mkdir -p "$HOME/.claude/hooks" && touch "$HOME/.claude/hooks/mcp-config-privacy-scanner.sh" && chmod +x "$HOME/.claude/hooks/mcp-config-privacy-scanner.sh"`	`mkdir -p .claude/hooks && touch .claude/hooks/prompt-injection-content-scanner.sh && chmod +x .claude/hooks/prompt-injection-content-scanner.sh`	`mkdir -p .claude/hooks && touch .claude/hooks/docker-image-security-scanner.sh && chmod +x .claude/hooks/docker-image-security-scanner.sh`
Config	`{ "hooks": { "PreToolUse": [ { "matcher": "Write\|Edit\|MultiEdit", "hooks": [ { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/mcp-server-url-allowlist.sh" } ] } ] } }`	`{ "hooks": { "PreToolUse": [ { "matcher": "Write\|Edit\|MultiEdit", "hooks": [ { "type": "command", "command": "$HOME/.claude/hooks/mcp-config-privacy-scanner.sh" } ] } ] } }`	`{ "hooks": { "PreToolUse": [ { "matcher": "Write\|Edit\|MultiEdit", "hooks": [ { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/prompt-injection-content-scanner.sh" } ] } ] } }`	`{ "hooks": { "postToolUse": { "script": "./.claude/hooks/docker-image-security-scanner.sh", "matchers": [ "write", "edit" ] } } }`
Citations	Source repositorymodelcontextprotocol.io 2026-07-20T14:55:19+00:00 Documentationcode.claude.com Submitted by JSONbored2026-06-05 Source methodology →	Source repositorygithub.com 2026-07-20T14:55:19+00:00 Documentationcode.claude.com Submitted by MkDev112026-06-05 Source methodology →	Source repositorygithub.com 2026-07-20T14:55:19+00:00 Documentationgenai.owasp.org Submitted by MkDev112026-06-05 Source methodology →	Source repositorygithub.com 2026-07-20T14:55:19+00:00 Documentationaquasecurity.github.io Source methodology →
Claim	Unclaimed	Unclaimed	Unclaimed	Unclaimed

Open 4 picks in the interactive comparison tool

Signals

Loading live community signals…

Citation facts

Review trust signals before you adopt

Source and provenance checks

Safety and privacy checks

Package and install checks

Compare-driven decision checks

CLI install

Balanced adoption plan

Pre-adoption checks

Security checks

Rollout

Evidence readiness matrix · balanced

Source provenance

Metadata review

Safety notes

Privacy notes

Package integrity

Install payload

Decision timeline · balanced

Confirm source provenanceRequired

Check metadata review statusRequired

Review safety notesRequired

Review privacy notes

Validate package integrity metadata

Verify install payload and commandsRequired

Prerequisite readiness

Safety & privacy surface

Safety notes

Privacy notes

Prerequisites

Schema details

About this resource

Features

Why use it

References

Source citations

Add this badge to your README

How it compares

Related resources

MCP Config Privacy Scanner - Claude Code Hook

Prompt-Injection Content Scanner - Claude Code Hook

Docker Image Security Scanner - Hooks

Claude Code Subagent MCP Scope Guide

Related guides

Auditing MCP Client Configuration Before Team Rollout

Choose the Right Claude Extension Surface

Managed MCP Allowlists for Enterprise Claude Code

Signals