Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Hooks docs omit `type: "mcp_tool"` hook handler [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#52191•Fetched 2026-04-23 07:34:11
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×4
RAW_BUFFERClick to expand / collapse

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/hooks

Section/Topic

Hook handler fields in the Hooks reference, plus the hook type overview in Automate workflows with hooks

Current Documentation

The hooks reference currently says:

Each object in the inner hooks array is a hook handler: the shell command, HTTP endpoint, LLM prompt, or agent that runs when the matcher matches. There are four types:

  • Command hooks (type: "command"): run a shell command.
  • HTTP hooks (type: "http"): send the event's JSON input as an HTTP POST request to a URL.
  • Prompt hooks (type: "prompt"): send a prompt to a Claude model for single-turn evaluation.
  • Agent hooks (type: "agent"): spawn a subagent that can use tools like Read, Grep, and Glob to verify conditions before returning a decision.

| type | yes | "command", "http", "prompt", or "agent" |

The guide also says:

Each hook has a type that determines how it runs. Most hooks use "type": "command", which runs a shell command. Three other types are available:

  • "type": "http": POST event data to a URL.
  • "type": "prompt": single-turn LLM evaluation.
  • "type": "agent": multi-turn verification with tool access.

What's Wrong or Missing?

Changelog v2.1.118 says hooks can now invoke MCP tools directly via type: "mcp_tool", but the current hooks docs still describe only four hook handler types and never mention mcp_tool.

That makes the reference inaccurate and leaves the new feature effectively undiscoverable. The current docs also use the phrase "MCP tool hooks," but the documented content is only about matching existing MCP tool calls in tool events, not configuring a hook handler that directly invokes an MCP tool.

Suggested Improvement

Update the hooks reference and guide to add type: "mcp_tool" as a documented hook handler type.

At minimum, document:

  • which hook events support mcp_tool
  • the required and optional fields for this handler type
  • how its execution/output behavior differs from command, http, prompt, and agent
  • a minimal JSON example showing a hook invoking an MCP tool directly
  • the distinction between matching MCP tool names like mcp__server__tool and using a hook handler with type: "mcp_tool"

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

PageContext
https://code.claude.com/docs/en/hooksHook handler fields says there are only four types and the type field only allows command, http, prompt, or agent
https://code.claude.com/docs/en/hooks-guideHook type overview says only three alternatives to command are available

Total scope: 2 pages affected

Source: Changelog v2.1.118

Exact changelog entry: Hooks can now invoke MCP tools directly via \type: "mcp_tool"``

extent analysis

TL;DR

Update the hooks reference and guide to include type: "mcp_tool" as a documented hook handler type to reflect the new feature introduced in Changelog v2.1.118.

Guidance

  • Review the current documentation on https://code.claude.com/docs/en/hooks and https://code.claude.com/docs/en/hooks-guide to identify all instances where hook handler types are mentioned.
  • Add type: "mcp_tool" to the list of supported hook handler types, including descriptions of its usage, required and optional fields, and execution/output behavior compared to other types.
  • Provide a minimal JSON example demonstrating how to invoke an MCP tool directly using a hook.
  • Clarify the distinction between matching MCP tool names and using a hook handler with type: "mcp_tool" to avoid confusion.

Example

An example JSON snippet for a hook invoking an MCP tool directly could look like:

{
  "type": "mcp_tool",
  "tool": "mcp__server__tool",
  "args": ["arg1", "arg2"]
}

This example assumes that mcp__server__tool is a valid MCP tool and arg1 and arg2 are required arguments, which should be replaced with actual values and tool names as per the MCP tool's documentation.

Notes

The update should ensure that all mentions of hook handler types across the affected pages are consistent and include type: "mcp_tool". It's also crucial to test the documentation changes to ensure they accurately reflect the functionality introduced in Changelog v2.1.118.

Recommendation

Apply the workaround by updating the documentation as suggested to include type: "mcp_tool" and provide clear guidance on its usage. This will enable users to utilize the new feature of invoking MCP tools directly via hooks.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#device allocation#model download#tokenizer error#prompt formatting#chain error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING