feat(mcp): add ServerSession.Notify for custom notification methods

[andylbrummer]

Summary

Adds a public Notify method on ServerSession that allows sending
notifications with arbitrary custom method names (e.g.
notifications/claude/channel). The method validates that the method
name starts with notifications/ per the MCP specification before
delegating to the underlying jsonrpc2 connection.

Motivation

The Go MCP SDK only exposes typed notification helpers (NotifyProgress,
SetLoggingLevel, etc.) for built-in MCP notification types. Protocol
extensions (e.g. Claude's channel mode) need to send notifications with
custom method names that aren't part of the core MCP spec. Currently
there's no public API to do this — handleNotify, getConn().Notify,
and the sending method handler are all unexported.

Changes

• Add (*ServerSession).Notify(ctx context.Context, method string, params any) error
• Validates method name starts with notifications/ prefix
• Delegates to getConn().Notify() which is the same path used by
  NotifyProgress and other built-in notification senders

Testing

The fork is used in production by agnt
with an end-to-end test that:

1. Creates an in-memory MCP client-server pair
2. Server sends notifications/claude/channel with structured params
3. Client reads the raw jsonrpc notification and asserts method + params match

Alternatives Considered

• Middleware-only approach: Client-side middleware can intercept
  custom notifications, but there's no way for the server to send them
  without this method.
• Raw jsonrpc2 access: Exposing the internal connection would break
  the abstraction boundary. A simple public method is cleaner.

🤖 Generated with Claude Code

[jba]

Please look at #745 and make sure you're solving the problem there. Also refer to that issue in the commit message.

[jba]

(No, you're not.)

[mikeschinkel]

Use-case wise — for Claude Channels — I have exactly the same need.

[jba]

You must go through middleware.

[maciej-kisiel]

Note: we already have one PR for this: #844 It looks more advanced than this one.

[mikeschinkel]

Following up. I created a fork of my own based on #844 so I could unblock my use-case. I have the send direction working end-to-end for notifications/claude/channel.

Steps

1. Forked modelcontextprotocol/go-sdk.
2. Applied @ajuijas's feat: implement generic SendNotification method for Issue #745 #844 commit on a send-notification branch (commit 6c3941f).
3. Added go.mod replace directive in Endless pointing at my fork.
4. Call site is just session.SendNotification(ctx, "notifications/claude/channel", notification).

Result:

• The x-notifications/ prefix from Expose generic SendNotification on ServerSession for custom protocol extensions #745 routes through the existing sending middleware pipeline. I think this addresses the "must go through middleware" concern @jba raised here.
• customNotificationParams allows passing arbitrary structs as params and still satisfies the SDK's internal Params interface, so payloads stay typed at the call site.
• Limitation: feat: implement generic SendNotification method for Issue #745 #844 is send-only. Inbound custom notifications still don't reach user code; no registered handler, no UnknownNotificationHandler-style hook. The channel push direction is what I needed for my use-case, but a permission-response flow back from Claude Code would hit a wall.

@jba @findleyr: Is there a specific blocker on #844; multi-session broadcast from #745, label state, anything else? Name it and I'll work on it, or work with @ajuijas on it, so I don't have to maintain a fork. And does inbound dispatch need to be addressed, or can that be a follow-up?

[jba]

Thanks for the work, @mikeschinkel.

A send-only solution isn't sufficient. There must be a story on the receive side.

I don't think we need to broadcast these notifications to all sessions. Progress and log notifications are confined to the server session's client, so the custom ones can be too.

We'd welcome your contribution, but I think it's clear we need a design sketch before proceeding. Please provide one on #745. Let's avoid continuing this discussion on this PR, and let's not write more code until we understand the solution.

[mikeschinkel]

@jba — Thanks. Moving to #745.