Implement SEP-1036: URL mode elicitation for secure out-of-band interactions

[cbcoutinho]

Summary

This PR implements SEP-1036: URL Mode Elicitation as specified in the merged specification PR, adding support for secure out-of-band interactions that bypass the MCP client.

Important

SEP 1036 has been merged into the main specification on 2025-11-13. This implementation is fully compliant with the final specification.

What is URL Mode Elicitation?

URL mode elicitation enables servers to direct users to external URLs for sensitive interactions without passing data through the MCP client or LLM context. This is critical for:

• OAuth Authorization: Third-party service authorization flows
• Credential Collection: Securely gathering API keys and passwords
• Payment Processing: Subscription and payment flows
• Sensitive Data: Any interaction requiring out-of-band handling

Key Changes

Type System (src/mcp/types.py)

• Error Code: Added URL_ELICITATION_REQUIRED (-32042) per specification
• Completion Notifications: Added ElicitCompleteNotification and ElicitCompleteNotificationParams
• Capabilities: Enhanced ElicitationCapability to support both form and url modes
• Progress Tracking: Added ElicitTrackRequest and ElicitTrackResult
• Error Data: Added UrlElicitationInfo and ElicitationRequiredErrorData structures
• Mode Field: Enhanced ElicitRequestParams with mode field and URL-specific parameters

Server Implementation (src/mcp/server/)

• URL Elicitation: Added elicit_url() method to ServerSession
• Helper Functions: Added typed helper functions (elicit_url(), elicit_form())
• Completion Notifications: Added send_elicit_complete() method for notifying clients
• Backward Compatibility: Maintained existing elicit() method for form mode

Client Implementation (src/mcp/client/session.py)

• Capability Negotiation: Updated to declare form and URL mode support
• Progress Tracking: Added track_elicitation() method for monitoring progress
• Notification Handling: Added handler for notifications/elicitation/complete

Comprehensive Test Coverage (tests/server/fastmcp/test_url_elicitation.py)

• URL elicitation with accept, decline, and cancel actions
• Helper function usage and typed result classes
• Completion notification sending and receiving
• Error code validation (-32042)
• Content field validation (omitted in URL mode)
• Backward compatibility with form mode
• Result: All 8 URL elicitation tests pass ✅

Specification Compliance

This implementation is 100% compliant with the merged SEP 1036 specification:

• ✅ Error code -32042 for URL_ELICITATION_REQUIRED
• ✅ Completion notification notifications/elicitation/complete
• ✅ Notification parameters with elicitationId field
• ✅ Mode values: "form" and "url"
• ✅ URL mode parameters: url and elicitationId fields
• ✅ Response actions: "accept", "decline", "cancel"
• ✅ URL mode responses omit content field
• ✅ Client capability structure for form and URL modes
• ✅ Backward compatibility with form mode elicitation

Breaking Changes

Capability Declaration (Required):

• Clients must now explicitly declare which elicitation modes they support during initialization
• For backward compatibility, an empty elicitation: {} is treated as { form: {} }

Mode Field (Required):

• ElicitRequestParams now requires a mode field ("form" or "url")

Testing

• ✅ 8 new URL elicitation tests - All passing
• ✅ 5 existing form elicitation tests - All passing
• ✅ Type checking (pyright) - Passes (pre-existing CLI warnings unrelated to changes)
• ✅ Linting (ruff format/check) - Passes

Migration Guide

For Server Developers

Before (form mode only):

result = await ctx.elicit(
    message="Enter your name",
    schema=NameSchema
)

After (URL mode):

result = await ctx.session.elicit_url(
    message="Authorize access to your files",
    url="https://example.com/oauth/authorize",
    elicitation_id="auth-001"
)

# After user completes auth at the URL
await ctx.session.send_elicit_complete("auth-001")

For Client Developers

Clients should declare support for URL mode during initialization:

capabilities = {
    "elicitation": {
        "form": {},  # Support form mode
        "url": {}    # Support URL mode
    }
}

Related

• Specification PR: modelcontextprotocol/specification#887 (Merged ✅)
• SEP Issue: modelcontextprotocol/specification#1036
• Specification Docs: URL Mode Elicitation

---

This PR includes comprehensive implementation of SEP 1036 with full specification compliance, backward compatibility, and thorough test coverage.

[cbcoutinho]

Howdy @maxisbey, the upstream spec has been merged so IMHO that this feature is now in Draft

[felixweinberger]

Hi @cbcoutinho thank you for working on this!

I think there are a couple of breaking changes here and the PR seems to introduce some types that don't match the merged spec change - e.g. we shouldn't be introducing messages sent over the wire that are Python specific like elicitation/track being introduced here.

We should be using the notifications/elicitation/complete notification to indicate that an elicitation has completed like we do in the TS implementation: modelcontextprotocol/modelcontextprotocol#887

[cbcoutinho]

Howdy @felixweinberger, thanks for your review. I've updated this PR, and implemented missing parts of the spec such as notifications/elicitation/complete. I believe this addresses your concerns - please let me know if there's anything else.

[felixweinberger]

Howdy @felixweinberger, thanks for your review. I've updated this PR, and implemented missing parts of the spec such as notifications/elicitation/complete. I believe this addresses your concerns - please let me know if there's anything else.

Thank you for the updates! Looking good now.

Pushed 2 commits on this branch:

• Added a ctx.elicit_url() wrapper to mirror ctx.elicit()
• Added server and client examples demonstrating the feature

[felixweinberger]

Failing some test coverage checks now, working on a fix

[felixweinberger]

@cbcoutinho fixed, feel free to take a look at the code I added if you're happy with it.

[cbcoutinho]

The entire MCP spec->implementation process has been incredible in terms of turn-around time - happy to have helped and really looking forward to using this once it's released.

Great additions @felixweinberger, thanks for looping me in.