Validate elicitation sub-capabilities in check_capability

[Rodrigo-Palma]

Connection.check_capability() (exposed publicly via ServerSession.check_client_capability) rejected a requested elicitation capability only when the client declared no elicitation support at all. It never inspected the form / url sub-capabilities, so a client that advertised only URL-mode elicitation would incorrectly pass a check for form-mode elicitation, and vice versa.

Handle elicitation the same way as sampling: when a specific mode is requested, require the client to declare that mode. A bare elicitation request is still satisfied by any elicitation support.

Fixes #2965

Motivation and Context

check_capability mirrors the (correct) sampling handling for the top-level presence check but omits the per-sub-capability checks that sampling performs for context / tools:

if capability.elicitation is not None and have.elicitation is None:
    return False

Because it only returns False when the client has no elicitation at all, a caller checking for form-mode elicitation against a URL-only client (or vice versa) gets a wrong True. This is public API, so once a caller relies on it (e.g. checking for form support before elicit_form), it silently returns incorrect results.

The fix adds the form / url sub-capability checks, matching the sampling pattern:

if capability.elicitation is not None:
    if have.elicitation is None:
        return False
    if capability.elicitation.form is not None and have.elicitation.form is None:
        return False
    if capability.elicitation.url is not None and have.elicitation.url is None:
        return False

Scope kept to elicitation. The issue also mentioned extensions and tasks as lower-priority gaps: extensions is already handled on main (SEP-2133), and tasks is left out to keep this tightly scoped — happy to follow up separately if desired.

How Has This Been Tested?

Extended the existing test_check_capability_per_field_branches parametrization in tests/server/test_connection.py with the elicitation branches: the two bug cases (URL-only client vs. form request, and form-only client vs. URL request), the matching positive cases, and the bare-request case. The two bug cases fail on main and pass with this change; the full test_connection.py suite is green (44 passed). ruff check, ruff format --check, and pyright are all clean on the changed files.

Docs: added a short "Ask only in a mode the client supports" section to docs/handlers/elicitation.md showing how a server uses check_client_capability to pick a form/url mode the client supports before eliciting. mkdocs build --strict passes.

Breaking Changes

No API change. check_capability now returns the correct False for a requested elicitation mode the client does not support (previously a wrong True). Callers that were (incorrectly) relying on the old always-true-when-any-elicitation behavior would see the corrected result.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

AI assistance: I used AI tooling to help analyze the issue, draft the fix, and scaffold the tests. I reviewed and understand the change, stand behind it, and can discuss it directly.

[cubic-dev-ai]

No issues found across 2 files

_{Re-trigger cubic}

[STiFLeR7]

Reviewed against current `upstream/main`'s `connection.py`: before this change, `check_capability` only checked `have.elicitation is None`, so a server calling `ctx.session.check_client_capability(ClientCapabilities(elicitation=ElicitationCapability(form=...)))` against a client that declared only `url`-mode elicitation would get `True` back — a false positive, since that client can't actually render a form. The fix's per-submode check (`form`/`url`) mirrors the existing pattern already used two lines above for `sampling.tools`, so it's consistent with how this method handles other nested sub-capabilities rather than introducing a new pattern.

The added test matrix in `test_connection.py` covers exactly the cases that matter: bare `ElicitationCapability()` still matches any elicitation support (no regression for existing callers that don't care about the mode), form-only vs url-only client in both directions correctly returns `False`, and matching submodes return `True`. That's the right shape for a capability-negotiation fix — it's easy to get "any None sub-field is a wildcard" backwards, and the test cases confirm the None-vs-declared-vs-mismatched semantics are all handled correctly.

The docs addition (`elicitation.md`) is a nice inclusion — without it, `check_client_capability` with a specific submode isn't obviously in scope for a tool author skimming the elicitation guide. CI green across the matrix. Looks correct to me.