fix(mcp): gate utility stubs on server-advertised capabilities

[nikolay-bratanov]

Summary

Fixes #18051. The four MCP utility schemas (list_resources / read_resource / list_prompts / get_prompt) are registered for every connected MCP server, even when the server advertises only the tools capability. Today's gate uses hasattr(server.session, required_method), which is always True because mcp.ClientSession defines all four methods on the class regardless of what the remote server actually supports.

The InitializeResult returned from await session.initialize() is the source of truth — result.capabilities.resources and result.capabilities.prompts are non-None only when the server implements those request types — but it was being discarded.

Changes

• MCPServerTask.__slots__: add "initialize_result".
• MCPServerTask.__init__: initialise self.initialize_result: Optional[Any] = None.
• All three await session.initialize() call sites (_run_http, _run_http reconnect path, _run_stdio): assign the result into self.initialize_result.
• _select_utility_schemas: when initialize_result is present, skip list_resources / read_resource if capabilities.resources is None, and skip list_prompts / get_prompt if capabilities.prompts is None. When initialize_result is None (older test fixtures, no real connect), fall back to the existing hasattr check so behaviour on that path is unchanged.

Verification

Direct unit-style test against a freshly patched tree (venv/bin/python against tools.mcp_tool):

from types import SimpleNamespace
from tools.mcp_tool import _select_utility_schemas, MCPServerTask

# tools-only server (Context7 case)
s1 = MCPServerTask("tools_only")
s1.session = SimpleNamespace(list_resources=lambda: None, read_resource=lambda x: None,
                              list_prompts=lambda: None, get_prompt=lambda *a: None)
s1.initialize_result = SimpleNamespace(capabilities=SimpleNamespace(
    tools=SimpleNamespace(listChanged=True), prompts=None, resources=None))
print([e["handler_key"] for e in _select_utility_schemas("x", s1, {})])
# -> []

# full-caps server
s2 = MCPServerTask("full")
s2.session = s1.session
s2.initialize_result = SimpleNamespace(capabilities=SimpleNamespace(
    tools=True, prompts=SimpleNamespace(), resources=SimpleNamespace()))
print([e["handler_key"] for e in _select_utility_schemas("x", s2, {})])
# -> ['list_resources', 'read_resource', 'list_prompts', 'get_prompt']

# legacy fallback (no initialize_result)
s3 = MCPServerTask("legacy")
s3.session = s1.session
print([e["handler_key"] for e in _select_utility_schemas("x", s3, {})])
# -> ['list_resources', 'read_resource', 'list_prompts', 'get_prompt']

End-to-end: I have this running locally against @upstash/context7-mcp (which is the canonical "tools-only" server). With the patch applied, _register_server_tools registers exactly two LLM-visible tools (mcp_context7_resolve_library_id, mcp_context7_query_docs) instead of the previous six.

Risk

• The new initialize_result slot is None until the first successful initialize(). The fallback path keeps existing behaviour for code paths that haven't reached that point yet.
• No production behaviour change for servers that do advertise prompts/resources — they get the same schemas as before.
• Minimal blast radius: one new slot, three single-line assignments, one if/else block in the existing utility-selection function. No public-API change.

Notes

I haven't added a unit test in this PR because the existing tests in tests/tools/test_mcp_tool.py mock ClientSession rather than the full connect/initialize flow, and adding a capabilities-gating test would require either a new fixture for InitializeResult or relaxing the existing fixtures. Happy to follow up with one in a separate commit if you'd like — let me know which fixture style you prefer.

[trevorgordon981]

LGTM. The fix is minimal, surgical, and addresses the root cause: the was being discarded, so we couldn’t gate utility stubs on actual server capabilities.

Verified:

• ✅ Unit test (inline) passes: tools-only server → , full-caps → all 4 utilities, legacy fallback → all 4
• ✅ All 182 MCP tool tests pass
• ✅ No breaking changes: defaults to , fallback preserves old behavior
• ✅ Low risk: one new slot, 3 assignments, one gated if/else block

The change correctly filters out , , , and for servers like that only advertise . Well done.

[trevorgordon981]

LGTM. The fix is minimal, surgical, and addresses the root cause: the initialize_result was being discarded, so we could not gate utility stubs on actual server capabilities.

Verified:

• Unit test (inline) passes: tools-only server -> [], full-caps -> all 4 utilities, legacy fallback -> all 4
• All 182 MCP tool tests pass
• No breaking changes: initialize_result defaults to None, fallback preserves old behavior
• Low risk: one new slot, 3 assignments, one gated if/else block

The change correctly filters out list_resources, read_resource, list_prompts, and get_prompt for servers like @upstash/context7-mcp that only advertise tools. Well done.

[teknium1]

Automated hermes-sweeper review found this fix is already implemented on current main via #21347.

Evidence:

• The linked issue discussion for MCP utility stubs (list_prompts / get_prompt / list_resources / read_resource) are registered even when the server doesn't advertise the corresponding capabilities #18051 has a maintainer note saying this was fixed in fix(mcp): gate utility stubs on server-advertised capabilities #21347 at 74c9c0eec9, with the same approach proposed here.
• tools/mcp_tool.py now stores MCPServerTask.initialize_result and captures await session.initialize() before tool discovery.
• _select_utility_schemas now gates list_resources / read_resource on capabilities.resources and list_prompts / get_prompt on capabilities.prompts, while preserving the old hasattr fallback when no initialize result is available.
• tests/tools/test_mcp_utility_capability_gating.py covers the Context7/tools-only case plus resources-only, prompts-only, full-capability, config-filter, and legacy-fallback behavior.
• The fix commit is present in release tag v2026.5.7.

Thanks for the original repro and root-cause analysis; it matches what landed on main.