Hooks vs Skills vs MCP
Hooks are event triggers: run this check, notification, formatter, or guardrail at a predictable lifecycle point. Skills are reusable instruction packages: follow this playbook, load these references, or apply this review method. MCP servers expose external capabilities: browser, GitHub, database, docs, monitoring, internal tools, or other structured data.
Do not use MCP when a hook can run a deterministic local command. Do not use a hook when Claude needs reusable domain knowledge. Do not put credentials or broad tool access in a skill file. Keep each control small enough that a teammate can explain what happens when it fails.
Control map
Hooks are best for repeatable events such as formatting, validation, or notifications.
MCP servers are best when Claude needs structured access to a tool, database, browser, repository, or internal system.
Skills are best for playbooks: how to reason about a domain, what references to load, and what checks to run.
Safe rollout
Start with read-only MCP access, test hooks locally, document expected side effects, and add write capabilities only after the workflow proves useful.
For a hook-to-MCP workflow, keep the hook deterministic and the MCP call scoped. Example: after Claude prepares a release note, a hook can run a local validation command, while MCP can fetch the related issue metadata. The hook should not silently publish, deploy, or write to external systems without approval.
Logging and troubleshooting
Log hook name, trigger, command, exit code, duration, and whether it blocked the task. For MCP calls, log server name, method, target, approval state, and outcome without storing secrets or raw tokens.
Common failures are stale credentials, missing local binaries, slow hooks, incorrect working directories, over-broad MCP permissions, and unclear error handling. Write the expected failure behavior before a team depends on the workflow.
Claude Code hooks not working: common fixes
If a hook never runs, confirm the trigger event, working directory, and that the local binary exists on PATH for the Claude Code session. If a hook runs but the task still proceeds, verify whether the hook is configured to block or only notify.
If MCP calls fail after a hook fires, check credential freshness, server startup order, and whether the hook assumes a tool that is not yet connected. Slow hooks often look like failures when the real issue is timeout or missing progress output.
Fix order: reproduce with one hook and one MCP server, log exit codes, test read-only access first, then widen permissions only after the owner reviews the failure log.
Recommended play
- Start with the control map before installing anything: hooks for deterministic events, MCP for external capability, skills for reusable process.
- Ship the first workflow read-only, then add write access only after the benefit is proven and the failure mode is documented.
- Connect every hook and MCP server to a visible owner, rollback path, and audit trail.
Hooks, MCP, and skills control map
Use this map to keep automation understandable as Claude Code workflows become more powerful.
| Area | Use for | Good examples | Risk to control |
|---|---|---|---|
| Hooks | Deterministic lifecycle actions | Format before completion, notify after task, run a local check | Unexpected side effects or slow workflows |
| MCP | Structured access to external tools and data | Browser, GitHub, database, docs, monitoring systems | Over-broad permissions and secret exposure |
| Skills | Reusable procedural knowledge | incident review workflow, code review workflow, release checklist | Outdated references or overly broad instructions |
| Manual approval | Destructive or production-facing changes | Deployments, data deletion, billing changes | Accidental write operations |
| Logs | Troubleshooting and audit trail | Hook trigger, MCP method, target, outcome, approval state | Secret leakage and noisy records nobody reviews |
Execution steps
Write the workflow boundary
Describe which action should happen automatically, which action needs a tool, and which action must stay human-approved.
Install read-only first
Add MCP servers and hooks with the smallest useful permission set so failures are observable without being destructive.
Document failure behavior
For each hook and MCP tool, write what happens when it times out, fails, returns empty data, or lacks credentials.
Promote after proof
Only widen permissions after the workflow has completed successfully on a small project and the owner agrees with the logs.
Add a troubleshooting note
Record the expected working directory, required binaries, credentials, timeout behavior, and rollback command before teammates copy the setup.
Common pitfalls
Using MCP for deterministic local steps
Prefer hooks for repeatable lifecycle actions and reserve MCP for external systems or structured tool access.
Adding write access too early
Keep the first rollout read-only and graduate one capability at a time.
No rollback path
Document how to disable each hook or server before it becomes part of team workflow.
Implementation checklist
- List every hook and MCP server by purpose.
- Mark read-only versus write-capable access.
- Document credentials and environment gates.
- Add a rollback path for failing hooks.
- Test the workflow on a small repo before broad rollout.
Questions this guide answers
When should you use Claude Code hooks instead of MCP?
Use hooks for deterministic lifecycle events such as formatting, validation, or notifications. Use MCP when Claude needs structured access to an external tool, database, browser, repository, or internal system. Do not use MCP when a hook can run the deterministic local command.
Why are Claude Code hooks not working?
Common causes are stale credentials, missing local binaries, slow hooks, incorrect working directories, over-broad MCP permissions, and unclear failure behavior. Log hook name, trigger, command, exit code, duration, and whether the hook blocked the task before widening permissions.
How should you roll out hooks and MCP safely?
Start read-only, test hooks locally, document expected side effects, and add write capabilities only after the workflow proves useful and the owner agrees with the logs.