Implement MCP Streamable HTTP Transport Protocol

[tendant]

Key Features

Implementation of the MCP Streamable HTTP transport specification

Implementation Details

Added server/streamable_http.go with the server-side implementation
Added comprehensive tests in server/streamable_http_test.go
Created example implementations:
    Full-featured server and client examples with notifications
    Minimal server and client examples for simpler use cases
Added detailed documentation in README-streamable-http.md

Summary by CodeRabbit

• New Features

  • Introduced a Streamable HTTP server implementation supporting session management, event streaming (SSE), direct JSON responses, and resumability for the MCP protocol.
  • Added flexible configuration options for session IDs, event stores, and context customization.
  • Provided in-memory event storage and replay functionality.

• Examples

  • Added runnable example programs for minimal and complete client-server interactions using Streamable HTTP transport, including notification handling and graceful shutdown.

• Documentation

  • Added a comprehensive README detailing protocol usage, server/client setup, configuration, and example workflows.

• Tests

  • Introduced a thorough test suite covering session initialization, SSE streaming, notification delivery, and session termination.

[coderabbitai[bot]]

Walkthrough

This change adds a comprehensive Streamable HTTP transport implementation for the Model Context Protocol (MCP) in Go, including a server with session and event stream management, client transport enhancements for resumability, extensive documentation, example programs demonstrating usage, configuration option implementations, and thorough test coverage for server behavior and origin validation.

Changes

File(s)	Change Summary
README-streamable-http.md	Added a detailed README documenting the MCP Streamable HTTP transport specification, server and client usage, protocol details, configuration options, and references to example programs.
examples/minimal_client/main.go examples/minimal_server/main.go examples/streamable_http_client/main.go examples/streamable_http_client_complete/main.go examples/streamable_http_server/main.go	Added new Go example programs demonstrating minimal and full usage of the MCP Streamable HTTP transport, including client initialization, JSON-RPC requests and notifications, tool invocation, server setup with tool registration, notification handling, and graceful shutdown.
server/streamable_http.go	Implemented the StreamableHTTPServer with session management, JSON-RPC over HTTP and SSE streaming, event storage and replay for resumability, notification buffering, HTTP method routing (POST, GET, DELETE), origin header validation, and flexible configuration via options. Introduced types for sessions, event stores (including in-memory), and utility functions to support streaming and session lifecycle management.
server/streamable_http_test.go	Added a comprehensive test suite for StreamableHTTPServer covering session initialization, SSE streaming, notification delivery, session termination, HTTP response validation, and concurrency handling in streaming scenarios.
server/http_transport_options.go	Implemented setter methods on StreamableHTTPServer for HTTP transport configuration options, assigning fields such as base path, dynamic base path function, keep-alive interval and enablement, context function, HTTP server instance, and base URL, replacing prior no-op stubs.
client/transport/streamable_http.go	Enhanced StreamableHTTP client transport by adding basic resumability support through tracking the last SSE event ID, sending it in the "Last-Event-Id" HTTP header on requests, updating SSE parsing logic to capture event IDs, and adding a getter method to retrieve the last event ID.
server/streamable_http_origin_test.go server/streamable_http_origin_validation_test.go	Added tests for origin header validation and allowlist logic in StreamableHTTPServer, covering exact and wildcard domain matches, localhost and loopback allowances, invalid origins, absence of origin header, and configuration via options to enforce origin restrictions.

Possibly related PRs

• mark3labs/mcp-go#168: Implements the basic client-side Streamable HTTP transport, which relates to the client transport enhancements and documentation added here.
• mark3labs/mcp-go#114: Refactors the MCP client to unify transport layers including Streamable HTTP support by introducing a new Client type and transport interface, related to the Streamable HTTP transport but focusing on client abstraction.

Suggested reviewers

• ezynda3

[!TIP]

⚡️ Faster reviews with caching

• CodeRabbit now supports caching for code and dependencies, helping speed up reviews. This means quicker feedback, reduced wait times, and a smoother review experience overall. Cached data is encrypted and stored securely. This feature will be automatically enabled for all accounts on May 16th. To opt out, configure Review - Disable Cache at either the organization or repository level. If you prefer to disable all data retention across your organization, simply turn off the Data Retention setting under your Organization Settings.

Enjoy the performance boost—your workflow just got faster.

✨ Finishing Touches

• [ ] 📝 Generate Docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[ezynda3]

This is great. One thing though. We recently merged some code around session management so that should be used in this PR as well. https://github.com/mark3labs/mcp-go/blob/main/server/session.go

[Gelembjuk]

+1

Thanks for your work. I am waiting this is approved to implement my idea where http streaming would be the best option

[tendant]

Thanks for working on this @tendant!

There are a number of features in SSEServer that are not present in the new StreamableHTTPServer that I think we should add:

// Keep-alive support
WithKeepAliveInterval(keepAliveInterval time.Duration)
WithKeepAlive(keepAlive bool)

// Dynamic path support
WithDynamicBasePath(fn DynamicBasePathFunc)

// Explicit handler mounting
func (s *SSEServer) SSEHandler() http.Handler
func (s *SSEServer) MessageHandler() http.Handler

These were added in #80 + #169 (for Ping support) and #214 (for dynamic path support) IIRC (if it helps to review them independently).

These are not defined in any interface, If we need similar features, we will have to use different function name if they are in the same server package. e.g. WithStreamableHTTPKeepAlive(keepAlive bool).

Is this acceptable? Doesn't look like a good solution.

Same logic applies to WithDynamicBasePath as well.

If we would like to support those options across multiple type of servers, it might better to create an option interface first.

[rwjblue-glean]

If we would like to support those options across multiple type of servers, it might better to create an option interface first.

Good point! I'll work on a PR for that this evening. Then once it lands it ought to be straightforward to use here.

[tendant]

If we would like to support those options across multiple type of servers, it might better to create an option interface first.

Good point! I'll work on a PR for that this evening. Then once it lands it ought to be straightforward to use here.

Sounds good. Please let me know as soon as it is in main branch, I will update this PR to use the new interface.

[tendant]

If we would like to support those options across multiple type of servers, it might better to create an option interface first.

Good point! I'll work on a PR for that this evening. Then once it lands it ought to be straightforward to use here.

Alternatively, we could move the different implementations (SSE and HTTP Streamable) into their own dedicated packages. This way, the options would be isolated per implementation and could be treated as internal details, rather than shared across all server types.

[rwjblue-glean]

Sounds good. Please let me know as soon as it is in main branch, I will update this PR to use the new interface.

I've just pushed https://github.com/mark3labs/mcp-go/pull/253 up for review. I specifically included a stub struct for StreamableHTTPServer, that you can delete once it lands and you can rebase.

[ezynda3]

Sounds good. Please let me know as soon as it is in main branch, I will update this PR to use the new interface.

I've just pushed #253 up for review. I specifically included a stub struct for StreamableHTTPServer, that you can delete once it lands and you can rebase.

Merged #253

[tendant]

Sounds good. Please let me know as soon as it is in main branch, I will update this PR to use the new interface.

I've just pushed #253 up for review. I specifically included a stub struct for StreamableHTTPServer, that you can delete once it lands and you can rebase.

Merged #253

Great. Thanks.

Still working on a few more test cases. I will update the PR once it is done.

[c1ngular]

is it possible to integrate this with existing web server ? i.e. i already have a remote web server setup and running , so just expose mcp http server interface without starting a additional http server ?

[Gelembjuk]

It is possible to integrate your MCP server by configuring a proxy in your web server. Servers like apache or nginx can be configured to forward requests for specific endpoints (/sse or /mcp etc) to another service running on specific port. IT is common thing but SSE can require some additional options to tell your proxy that this is SSE

[ezynda3]

Closed in favor of #273