Skip to content

Single MCP server instance should work across multiple projects #63

Closed
#67
#65
Closed
Single MCP server instance should work across multiple projects#63
#67
#65

Description

@PatrickSys
PatrickSys
opened on Mar 6, 2026

The problem

The server resolves one project root at startup (CODEBASE_ROOT env var to the cwd) and then every tool call runs against that root for the rest of the process lifetime.

If you work on more than one project, you need a separate MCP server entry per project in your config, each with a hardcoded path. It works, but it's annoying to maintain and doesn't scale.

It gets worse in editors like Codex Desktop where cwd doesn't reliably point to the project root . @aolin480 ran into this and explored walk-up detection (looking for .codebase-context/, .git, nx.json etc. as markers), but it touched too much of the internals to land cleanly. See the discussion in #2.

What needs to change

The root path can't be a process-level singleton. ROOT_PATH is resolved once in resolveRootPath() and baked into PATHS and indexState - these need to become per-project instead of global.

Whatever the approach ends up being (per-tool parameter, walk-up detection, or something else), the main thing to get right is the caching layer: loading and managing indexes for multiple roots without re-parsing everything on every call, and without leaking memory if someone points it at 20 different repos over a long session.

Credit to @aolin480 for surfacing this in #2.

Activity

  1. PatrickSys commented on Mar 7, 2026

    @PatrickSys
    PatrickSys
    on Mar 7, 2026
    OwnerAuthor

    Opened PR #65 to address this: #65

    What changed:

    • request-level project routing for MCP tool calls instead of always using the startup root
    • optional project_directory selection plus deterministic ambiguity handling when multiple roots are active
    • lazy per-project initialization instead of eager prewarming for every announced root
    • regression coverage for explicit routing, ambiguous multi-root sessions, and resource behavior

    Verification completed:

    • pnpm type-check
    • targeted routing/index migration suites
    • full pre-push hook run (Prettier + full Vitest suite, 50 files / 292 tests)

    I am not manually closing the issue before merge. The PR body uses Closes #63, so GitHub will close it automatically on merge once the fix is actually landed.

  2. PatrickSys
    closed this as completedin #65on Mar 7, 2026

  3. PatrickSys commented on Mar 8, 2026

    @PatrickSys
    PatrickSys
    on Mar 8, 2026
    OwnerAuthor

    Update on this work:

    The final cut here is smaller and more honest than the earlier branch direction.

    What is fixed:

    • the old single-root MCP architecture is gone
    • one codebase-context MCP server can now serve multiple projects in one session
    • the server no longer depends on cwd for MCP project routing
    • ambiguous multi-project calls fail with selection_required instead of guessing the wrong repo
    • explicit project can target a repo path, file path, file:// URI, or monorepo subpath

    What this means for the original problem:

    What this does not claim:

    The public docs were also cut back so the setup story is now:

    1. start with one codebase-context server and no project path
    2. if a call returns selection_required, retry with project
    3. if you only use one repo, you can still append one project path as a fallback

    PR: #67

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions