RFD: Server-to-Client Logging #392
Open
+178
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Proposes a `log` notification method that allows agents to send diagnostic messages (errors, warnings, info, etc.) to clients. Key features: - Optional sessionId for session-scoped vs connection-wide messages - 8 severity levels (RFC 5424/MCP-compatible) - Optional structured data, error codes, and timestamps - Follows ACP naming conventions (no namespace, like initialize/authenticate) Co-Authored-By: Claude <noreply@anthropic.com>
- Fix transport-agnostic language (stderr is stdio-specific) - Add comparison table with MCP, LSP, A2A, AG-UI - Clarify key design choices vs other protocols Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude <noreply@anthropic.com>
Explains that `log` notifications (in-band, user-facing) and OTEL telemetry export (out-of-band, observability) are complementary. Co-Authored-By: Claude <noreply@anthropic.com>
- Connection-level messages are essential (pre-session errors) - Separation of concerns (logs != conversation state) - Can't require capability negotiation (pre-initialize errors) - Clarify: JSON-RPC errors for request failures, log for out-of-band Co-Authored-By: Claude <noreply@anthropic.com>
JSON-RPC 2.0 notifications are fire-and-forget - clients safely ignore unknown methods. No version negotiation required. Co-Authored-By: Claude <noreply@anthropic.com>
Key insight: JSON-RPC errors terminate the run, log notifications don't. Changes: - Add `logging` capability requirement (non-breaking, clean opt-in) - Clarify the core question: "should the run stop?" - Non-fatal issues, warnings, degraded functionality shouldn't abort - Connection-wide issues, out-of-band timing, alternative patterns Co-Authored-By: Claude <noreply@anthropic.com>
Major revision: - Require capability negotiation (non-breaking, opt-in) - Lead with key insight: JSON-RPC errors terminate, log doesn't - Consolidate FAQ from 12 to 8 focused questions - Add "why not separate channel" FAQ (transport-agnostic, etc.) - Fix connection-wide example (before session/new, not multi-session) - Remove redundant/contradictory text - 176 lines (down from 323) Co-Authored-By: Claude <noreply@anthropic.com>
MCP server disconnection is a session-level concern, not a good example for run-time log notifications. Better examples are backing model rate limiting and backing service disconnection. Co-Authored-By: Claude <noreply@anthropic.com>
Use generic examples (server shutting down, configuration problems) instead of MCP-specific examples for connection-wide error scenarios. Co-Authored-By: Claude <noreply@anthropic.com>
Addresses the alternative of sending diagnostic info as fake agent_message_chunk content. Co-Authored-By: Claude <noreply@anthropic.com>
- Add "purely informational" to elevator pitch - Add explicit statement that clients MAY display but MUST NOT take automated action - Remove top-level code field (error codes don't make sense for info/debug messages) - Clarify data field is opaque, for display/debugging only Co-Authored-By: Claude <noreply@anthropic.com>
The "why" is already covered in Status quo (gaps/problems) and FAQ (why not alternatives). Elevator pitch should be punchy. Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This RFD proposes a
lognotification method that allows agents to send diagnostic messages (errors, warnings, info, etc.) to clients.Key features
sessionId: Connection-wide if absent, session-specific if presentinitialize/authenticatepattern (no namespace)Problem
Servers currently have no way to proactively notify clients about errors, warnings, or diagnostic information outside of request-response cycles:
SessionNotificationrequires asessionId, so can't send connection-wide messagesExample
{ "jsonrpc": "2.0", "method": "log", "params": { "level": "error", "sessionId": "abc-123", "logger": "mcp.database", "message": "Connection to MCP server 'database-tools' failed", "code": -32001, "timestamp": "2025-01-21T10:30:00Z", "data": { "retryIn": 5 } } }🤖 Generated with Claude Code