Auto-load CLAUDE.md from MCP server directories at session start

Resolved 💬 3 comments Opened Mar 10, 2026 by aoliveira-sword Closed May 4, 2026

Summary

Claude Code automatically loads CLAUDE.md files from the current project directory and its parents, injecting them as context before the model acts. However, this does not extend to MCP servers — if an MCP server ships a CLAUDE.md at its root directory, Claude never reads it, so any interaction patterns or usage instructions defined there are silently ignored.

Problem

MCP tool description fields are useful for simple tools, but insufficient for servers that define multi-step interaction flows, conventions, or behavioral instructions. A CLAUDE.md at the MCP server root is a natural place to document these — but it only works if Claude Code loads it.

Expected Behavior

At session start, Claude Code should:

  1. Iterate over all configured MCP servers
  2. For each stdio-type server, resolve the server's root directory from the command/args path
  3. If a CLAUDE.md exists there, inject its contents into the system context (same mechanism used for project-level CLAUDE.md files)

Current Workaround

A UserPromptSubmit hook that reads ~/.claude.json, resolves each MCP server's directory, finds its CLAUDE.md, and outputs the content to stdout (which Claude Code injects as a <system-reminder>). This works but requires manual setup and shouldn't be necessary.

Impact

Without this, any MCP server that relies on a CLAUDE.md to define its interaction model is effectively broken out of the box — the instructions exist but are never seen by the model.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗