Allow MCP tools to be exposed without requiring an index at the MCP server root path

[MaiLunJiye]

Problem

In a monorepo, CodeGraph works best when indexes are created at smaller project or service directories rather than at the repository root.

For example:

repo/
  service_a/.codegraph/
  service_b/.codegraph/
  service_c/.codegraph/

The MCP tools already support projectPath, so an agent can query a specific indexed service:

{
  "projectPath": "/path/to/repo/service_a"
}

However, if the MCP server is started from a directory that does not itself contain .codegraph/, the server appears inactive and does not expose any MCP tools. This means the agent cannot call the tools at all, even if every intended query would pass a valid projectPath pointing to an indexed subproject.

Why This Hurts

For large monorepos, indexing the repository root is undesirable:

• the root index can be very large and slow
• broad root-level queries can accidentally expand across unrelated services
• each service may be an independent build/deploy unit
• users may intentionally want service-level indexes only

Today, the workaround is to create a small anchor project with a .codegraph/ index and start MCP with:

codegraph serve --mcp --path /path/to/anchor

Then every real query passes projectPath.

This works, but it is unintuitive and easy to misconfigure.

Expected Behavior

It would be useful to have an option to expose MCP tools even when the MCP server root path has no .codegraph/, as long as queries provide projectPath.

For example:

codegraph serve --mcp --allow-project-path-only

or:

codegraph serve --mcp --expose-tools-without-root-index

Then:

• tool discovery would still expose explore, node, search, callers, etc.
• calls without projectPath could return a clear "no index at server root" error
• calls with a valid indexed projectPath would work normally

Actual Behavior

If the MCP server root path has no .codegraph/, the MCP tools are not exposed, so the agent cannot call codegraph_explore, codegraph_node, etc., even with a valid indexed projectPath.

Suggested Solution

Separate MCP tool exposure from the default root project index.

The server could expose tools in a "projectPath required" mode when no root index exists. Each tool invocation would then validate the provided projectPath and use that project's .codegraph/.

This would better support monorepos and multi-service repositories where indexing the root is intentionally avoided.

[iacore]

Same here. I want to operate on two projects but current MCP server is too stupid to know how to use codegraph on another repo. Also, when codegraph init isn't called yet, but will be called by the agent, the MCP server doesn't provide tools after the agent initialized the codegraph index.

I think it is a generally bad design to gate the tool use on whether an index is available at ./.

[colbymchenry]

Shipped in #966 (merged to main; ships in the next release) — thanks for the clear reports, @MaiLunJiye and @iacore.

The MCP server no longer hides its tools when it starts in a directory without a .codegraph/. Gating tool availability on an index at ./ was the design @iacore flagged, and it's gone: the tools are always exposed now. Point any call at an indexed project with projectPath (its path, or anywhere inside it) and CodeGraph answers from that project's index — so a monorepo where only sub-services are indexed, or a second repo in the same session, just works. A path with no index returns clean "use your built-in tools / run codegraph init" guidance instead of erroring. This also covers the "ran codegraph init mid-session but the tools never showed up" case — they're listed from the start, and a new index is picked up on the next call.

As a bonus, the Claude front-load hook is monorepo-aware now too: at a monorepo root it looks into sub-projects and front-loads the one your question references (or lists them so you can pass projectPath).

Appreciate the push on this one.