SEP-2282: Server-Declared Behavioural Hooks#2282
SEP-2282: Server-Declared Behavioural Hooks#2282heyhayes wants to merge 3 commits intomodelcontextprotocol:mainfrom
Conversation
Propose a new `hooks` field in MCP ServerCapabilities that allows servers to declare lifecycle hooks — context injections triggered by client-side events (session start, post-tool-use, session end, etc.). This enables servers to participate in the behavioural lifecycle that all three major AI coding clients have independently built, without client-specific code. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Run prettier on SEP markdown and npm run generate:seps to produce the required .mdx and docs.json entries. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
I feel that calling this "hooks" might be misleading since they're more like 'just in time instructions' or 'lifecycle scoped instructions.' The existing client hooks (Claude Code, Codex CLI, Gemini CLI) execute shell commands deterministically, and the SEP's own motivation is built on a bash script that reliably fired and produced output. Am I understanding this SEP correctly, or are the hooks in this proposal actually meant to do the same? |
@olaservo Hey, The problem I'm solving concretely: I am developing a semantic memory server (Annal) and agents naturally search it when they hit knowledge gaps, but they forget to store what they've learned because there's no lifecycle point where the server can remind them. Right now I'm working around it with git post-commit hooks that shell out, but that only catches commit boundaries — everything between commits is lost. If the server could inject "review what you just learned and store anything worth preserving" after a subagent returns, the memory quality problem largely solves itself. Happy to rename throughout the SEP to something like "lifecycle instructions or JIT instructions" if that makes the intent clearer. Best David |
localden
changed the title
3 participants
Summary
This SEP proposes a new
hooksfield in MCPServerCapabilitiesthat allows servers to declare lifecycle hooks — context injections triggered by client-side events such as session start, post-tool-use, and session end.The core observation: all three major AI coding clients (Claude Code, Codex CLI, Gemini CLI) have independently built client-side hook systems, but MCP servers have no way to participate in them through the protocol. Servers that need behavioural integration — like memory systems that want to remind agents to store learnings at natural breakpoints — must currently reverse-engineer each client's hook configuration format separately.
Key design decisions
ServerCapabilities, not callbacks or executable code.suggestion,important,required— clients control which levels they honour.Evidence
Built from real-world experience with Annal, a semantic memory MCP server. The
annal installCLI currently writes hook configs into three different client settings files (190 lines of client-specific code). With staticSERVER_INSTRUCTIONSalone, an agent stored only 2 memories across a full implementation session. With a post-commit hook injecting a one-line reminder, storage behaviour changed immediately.Seeking sponsor
Looking for a maintainer sponsor to shepherd this through review. The proposal touches on server capabilities, client-server negotiation, and agent behaviour — happy to iterate on any aspect.
🤖 Generated with Claude Code