feat(mcp): let operators disable individual built-in tools

[vishal-bala]

list-indexes, search-records, and upsert-records all registered unconditionally, so an operator who wanted a narrower tool surface had no way to get one. A deployment that should never advertise writes still published upsert-records whenever any binding was writable, and a single-purpose server still published discovery.

The config

server:
  builtin_tools:
    upsert-records: disabled

Omitted names stay enabled, so existing configs are unaffected. Only the three real names are accepted: search_records with underscores fails at startup rather than silently disabling nothing while reading as though it had.

Two unusable-but-valid tool surfaces now warn

Both shapes are legal config that presents to a client as a server that simply does not work, and both were previously silent:

• Everything disabled leaves a server that connects and offers nothing. The warning deliberately does not name a cause, since upsert-records can also be absent because every binding is read-only.
• Discovery disabled on a multi-index server leaves search-records demanding a logical index id that clients have no way to learn — its own description tells them to call list-indexes first.

Neither is fatal, because an operator may be mid-rollout.

The multi-index discovery case had no coverage anywhere, so this adds it, along with the negative case: with a sole binding the index argument defaults, so disabling discovery there is legitimate and stays quiet. I verified by mutation that the new test fails when the warning condition is neutered.

Verification

• MCP unit tests: 237 passing
• make check-types: clean
• Pre-commit: passing

Note on sequencing

This is independently useful and mergeable on its own. It is also a prerequisite for the custom tool profiles work that follows, since a profile name must be checked against the built-in names this PR introduces.

---

Note

Medium Risk
Changes which MCP tools clients see and discovery/write advertising; misconfiguration can yield empty or hard-to-use tool surfaces, though defaults preserve existing behavior and validation plus warnings reduce silent failures.

Overview
Adds server.builtin_tools so operators can disable any of list-indexes, search-records, or upsert-records individually (omitted tools stay enabled). Unknown names fail at startup validation instead of being ignored.

Registration gates each built-in on config; list-indexes sets upsert_available to false when upsert is disabled even if bindings are writable. On multi-index servers with discovery off, search and upsert tool descriptions inline logical index ids. Startup warnings cover empty tool lists, discovery disabled with multiple indexes, and config changes after tools were already registered (process restart required to change the published surface).

Docs in docs/concepts/mcp.md describe the config and behavior.

^{Reviewed by Cursor Bugbot for commit f323df5. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c4d3485. Configure here.}