Hooks, MCP, and Plugin Issues

This page helps you diagnose issues with Hooks, MCP servers, and plugins.

Check these two things first

Before digging into a specific component, rule out the two most common causes:

Is the directory trusted? Untrusted workspaces do not load project-level settings, Hooks, MCP, or project-level Agents (in interactive sessions, hooks are blocked outright). Entering a directory for the first time shows a trust prompt with "this session only" or "remember" (written to settings.local.json); you can also permanently trust frequently used directories with permissions.trustDirectories. See Permissions and Directory Trust.
Did you reload after changing configuration? Most extensions support hot reloading, which is faster than restarting — /mcp reload, /plugins reload, /skills reload, /agents reload; settings marked "restart required" still need a CLI restart.

When a hook does not fire or behaves unexpectedly:

Event and matching: confirm the hook is bound to the correct event name and that the matcher matches the target (empty or * matches everything; exact values, | multi-values, or regex).
Exit codes: command-type hooks control flow via exit codes — 0 succeeds, 2 blocks (stderr is fed back to the Agent), anything else is a non-blocking error. If a hook unexpectedly blocked an operation, check whether it returned 2.
Input parsing: hooks receive JSON on stdin (including session_id, cwd, hook_event_name, and so on); confirm your script reads it correctly.
Executable permission: the script pointed to by command needs executable permission and a correct path.
Use /hooks to view the registered hooks.
Full reference: Hooks Reference.

When an MCP server does not connect or its tools are unavailable:

Use /mcp to view server connection status.
Command and paths: for the stdio type, confirm command, args, and cwd are correct and the server starts standalone.
Project-level approval: project-level MCP servers require per-server approval by default. Approve them with mcp.enableAllProjectMcpServers or mcp.enabledProjectMcpServers.
Allowlist filtering: check whether the server is filtered out by mcp.allowed / mcp.excluded, --allowed-mcp-server-names, or --strict-mcp-config.
Authentication: for HTTP/SSE types, confirm the authentication information in headers is correct.
Timeout: for slow connections, adjust the timeout field.
MCP settings are marked "restart required"; after changing them, try /mcp reload first, and restart if it still does not take effect.
Full reference: MCP Reference.

When a plugin does not load or components are missing:

Use /plugins to view installed plugins.
Manifest: the manifest lives at .qoder-plugin/plugin.json (omittable); if declared, confirm name is valid (kebab-case, no spaces).
Directory structure: components must live in the conventional directories (commands/, agents/, skills/, hooks/hooks.json, .mcp.json, and so on), or have paths explicitly declared in the manifest.
Security restrictions: when security.blockGitExtensions is true, loading plugins from Git is blocked; when security.allowedExtensions is non-empty, only matching sources are allowed.
Full reference: Plugins Reference.