Make MCP endpoint Streamable HTTP compliant and fix Claude Desktop setup - #253
Merged
Merged
Conversation
…p setup Route GET/POST/DELETE /mcp through the mcp gem's StreamableHTTPTransport (stateless, JSON responses) instead of calling MCP::Server#handle_json directly. Notifications now get 202, GET gets 405 instead of the HTML 404 page, malformed JSON gets a 400 parse error, and Accept/Content-Type and MCP-Protocol-Version are validated. The request body cap is raised to 16 MB so base64 image uploads keep working. The documented Claude Desktop config (url + headers) is not supported by claude_desktop_config.json, which only runs stdio servers; document the mcp-remote bridge instead. Fix the Claude Code command (--transport http, options before the name, local default scope). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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
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
The
/mcpendpoint skipped the HTTP side of the MCP Streamable HTTP spec. The documented Claude Desktop config also couldn't work.Endpoint
Mcp::SessionsControllerpassed the raw body toMCP::Server#handle_json. It now routesGET/POST/DELETE /mcpthrough the gem'sStreamableHTTPTransport, set up so nothing is kept between requests and responses are plain JSON.notifications/initialized200with body"null"202, empty bodyGET /mcp(SSE probe)404HTML page405DELETE /mcp404HTML page200200with an error400with error code-32700The transport also checks
Accept/Content-Typeand theMCP-Protocol-Versionheader, and supports the 2026-07-28 protocol version. The body limit is raised from the transport's 4 MiB default to 16 MB, so base64 image uploads over about 3 MB keep working.Docs
claude_desktop_config.jsononly runs stdio servers, so the documentedurl+headersentry was ignored. The docs now use themcp-remotebridge (needs Node.js).--transport http(notstreamable-http) with options before the server name, and the docs give the correct default scope (local).Behavior change
Clients must send
Content-Type: application/jsonand anAcceptheader that includesapplication/json. Claude Desktop (viamcp-remote), Claude Code and the official SDKs already do. The old standalone SSE transport (2024-11-05) is still not supported.Testing
bin/rails test: 1556 runs, 0 failures.bin/rubocopandbin/brakemanare clean.mcp-remote.🤖 Generated with Claude Code