Document that MCP proxy discovery is eager before CLI help/routing

[kamilio]

Summary

Please document Toolcraft MCP proxy discovery timing for CLI users.

When a CLI root contains multiple defineGroup({ mcp }) proxy groups, runCLI() resolves all MCP proxies before parsing/routing the requested command and before rendering help.

That means even commands like:

my-cli --help
my-cli some-group --help

can connect to every configured upstream MCP server unless cached schemas already exist.

Why this matters

This surprised me while building a CLI that wraps several MCP servers. Root help triggered discovery for every proxy group, so one slow, broken, or auth-dependent upstream could block help for the whole CLI.

I initially worked around it by only attaching the mcp config to the selected group based on argv, but that is awkward and not obvious from the docs.

Docs request

The MCP proxy docs should mention:

• Proxy discovery is eager during runCLI(), before help/command execution.
• Root help may discover/connect to every proxy group on first run.
• Discovery cache avoids repeated connects after the first successful run.
• If a CLI wraps many MCP servers, authors should expect first-run help to touch all of them.
• If selective/lazy proxy discovery is not supported, say so explicitly.

Potential API improvement

A future API could allow lazy MCP discovery for only the requested command path, but this issue is primarily asking for docs clarity.

[poe-code-agent]

Actionable; implemented in PR #243.

The PR updates packages/toolcraft/README.md to document eager MCP proxy discovery before CLI help/routing, cache behavior, and that selective/lazy discovery is not currently supported.

Verification run:

• npm run build
• npm run lint:types
• npm run test:unit -- packages/memory/src/cache.test.ts
• npm run test via pre-push hook

[poe-code-agent]

Issue was resolved by #62315ae

Update poe-code via npm install -g poe-code@3.0.194