docs: correct multi-instance MCP guidance to lead with per-project scoping#144
Merged
Merged
Conversation
…oping The troubleshooting section previously recommended a CLAUDE_CONFIG_DIR per-project wrapper as the fix for MCP servers disconnecting under concurrent Claude Code instances. That wrapper has a significant undocumented downside: Claude Code ties its login to the default config directory (the macOS Keychain credential is not shared across CLAUDE_CONFIG_DIR values), so every isolated config requires its own /login with no clean way to share a session. Rewrite the section to lead with the actually-correct practice: - Scope every MCP server to the project that needs it. marko-mcp/lsp/skills are enabled per project by devai:install via the project's .claude/settings.json; do not also enable them globally (that launches and fails marko-mcp in every non-Marko project). Other project-specific servers belong in a project-root .mcp.json. - Reduce write churn: fewer concurrent instances, CLAUDE_CODE_SKIP_PROMPT_HISTORY=1. - Demote CLAUDE_CONFIG_DIR isolation to an "advanced, rarely worth it" note that discloses the per-project /login requirement. Heading (and its anchor) is unchanged, so the devai:install tip link still resolves. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
the
documentation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Follow-up to #143. That PR's troubleshooting section recommended a
CLAUDE_CONFIG_DIRper-project wrapper as the fix for MCP servers disconnecting under concurrent Claude Code instances. Testing surfaced a significant downside that wasn't documented: Claude Code ties its login to the default config directory — the macOS Keychain credential is not shared acrossCLAUDE_CONFIG_DIRvalues, so every isolated config requires its own/login, with no clean way to share a session. That makes the wrapper poor primary advice.What
Rewrite the section to lead with the correct practice and demote the wrapper:
marko-mcp/marko-lsp/marko-skillsare enabled per-project bydevai:install(project.claude/settings.json); enabling them globally makes marko-mcp launch and fail in every non-Marko project. Other project-specific servers belong in a project-root.mcp.json(n8n example included).CLAUDE_CODE_SKIP_PROMPT_HISTORY=1.CLAUDE_CONFIG_DIRisolation to an "advanced, rarely worth it" note that discloses the per-project/loginrequirement.The section heading (and its anchor) is unchanged, so the
devai:installtip link still resolves.Verification
pest packages/devaiInstallCommandTest — 12 passed (tip text/URL unchanged)pest packages/docs-markdown— 17 passed