Decouple client transports from `*http.Client` by accepting an interface

[manuelibar]

Problem

Currently, the StreamableClientTransport and SSEClientTransport requires a concrete *http.Client, which restricts its integration into systems with established HTTP client abstractions. This tight coupling forces users to implement workarounds when integrating the MCP client into environments with standardized middleware for concerns like authentication, tracing, and metrics.

As seen in issues #367 and #373, users are already creating custom RoundTripper implementations to inject headers and other middleware. This becomes particularly cumbersome in enterprise settings where HTTP clients are expected to handle numerous cross-cutting concerns, such as:

• Authentication: OAuth2, API keys, mTLS, and other custom schemes.
• Observability: Distributed tracing (OpenTelemetry), metrics collection (Prometheus), and structured logging.
• Resilience: Circuit breakers, retry logic, and custom timeout policies.
• Security & Compliance: Request/response auditing and rate limiting.

Forcing the use of a concrete *http.Client makes it difficult to reuse existing, instrumented clients, leading to duplicated logic or complex wrapper patterns around the MCP client.

Solution

To enhance flexibility and composability, StreamableClientTransport should accept an interface that satisfies the Do method, rather than a concrete *http.Client.

A standard HTTPClient interface could be defined as:

type HTTPClient interface {
    Do(req *http.Request) (*http.Response, error)
}

This change would be fully backward-compatible, as *http.Client already implements this method signature. Users could continue to initialize the transport as before:

// Existing usage remains unchanged and valid
&mcp.StreamableClientTransport{
    Endpoint:   endpoint,
    HTTPClient: &http.Client{},
}

However, it would also empower users to inject their own custom or instrumented HTTP client implementations:

// Enables integration with custom, standardized clients
&mcp.StreamableClientTransport{
    Endpoint:   endpoint,
    HTTPClient: myOrg.NewInstrumentedHTTPClient(), // Custom implementation
}

This approach aligns with Go's design principle of "accept interfaces, return structs," promoting loose coupling and greater flexibility.

Alternatives

1. Custom http.RoundTripper: While this is the current workaround (as demonstrated in Add client examples for streamable http #367), it is suboptimal. Middleware implemented at the transport layer is less flexible and harder to compose than middleware applied to a client abstraction.
2. Wrapper Pattern: Creating a wrapper around the entire MCP client introduces unnecessary complexity, adds a layer of indirection, and may have performance implications.

The proposed interface-based approach is cleaner and more idiomatic than these alternatives.

Additional context

Adopting an interface for the HTTP client is a standard best practice in the Go ecosystem, used by major libraries to ensure interoperability and extensibility:

• AWS SDK for Go (v2)
• Google Cloud Go libraries
• OpenTelemetry instrumentation libraries
• Popular HTTP clients like Resty and go-retryablehttp

Implementing this change would make the go-sdk more enterprise-friendly and easier to test, as it would allow users to mock the HTTPClient in their unit tests. It would also provide a more robust and idiomatic solution to the use cases described in issues #367 and #373.

[findleyr]

CC @jba

This might be an elegant solution, and wouldn't affect the implementation significantly. Given that it doesn't break existing code (since http.Client is still a concrete implementation of this interface), and we're considering a similar decoupling in #518, should we do this?

Alternatively, we can add a separate option that adds an 'abstract client'.

[manuelibar]

Hi @findleyr, just an FYI that a PR for this is in the oven!
Looking forward to your feedback! 👍

[jba]

cc @neild @bradfitz I believe our usual answer is to implement RoundTripper. Does anything here suggest otherwise?

[jba]

Adopting an interface for the HTTP client is a standard best practice in the Go ecosystem, used by major libraries to ensure interoperability and extensibility:

• AWS SDK for Go (v2)

I haven't explored this much, but I did find https://pkg.go.dev/github.com/aws/aws-sdk-go/aws#Config.HTTPClient.

• Google Cloud Go libraries

I can't find an example .

• OpenTelemetry instrumentation libraries

I can't find an example.

• Popular HTTP clients like Resty and go-retryablehttp

The resty client is a struct, not an interface.

[neild]

I haven't looked at all the context for this, but in general if you want to implement an abstraction over HTTP client operations you should implement http.RoundTripper.

@manuelibar, you say this is suboptimal because "Middleware implemented at the transport layer is less flexible and harder to compose than middleware applied to a client abstraction." What specifically is less flexible and harder to compose about a RoundTripper? What behavior do you want to add or modify that can't be provided in RoundTripper?

On composition, adding a client interface separate from RoundTripper seems like it would make composition much harder--if all middleware implements RoundTripper then composition is straightforward, but if some implements RoundTripper and some the new client interface then composition is difficult.

[fgrosse]

This is basically what we were discussing over here: #367 (comment)

I wrote down why I think this is the best way forward in the same ticket here: #367 (comment)

Edit: I see this was already mentioned in the issue description.

---

Regarding the question about composition: Adding the interface makes it simple to implement a middleware because it is immediately clear what is needed (i.e., a type implementing that single Do function). Since the http.Client from the standard library already implements it, this is also compatible with the existing approach of changing the RoundTripper implementation, which means it does not harm composability.

I see the following problems with the round-tripper approach:

1. It is not a good UX: To understand how to do simple things, such as adding custom request headers (e.g., for authorization), is not obvious. Instead, it's hidden in the HTTP client implementation, and unless users are very familiar with it, they probably won't think to change the round tripper implementation to add a header or make any other change to the request. It feels much more like a hack than a feature.
2. The standard library itself documents that round trippers should not modify requests. This makes it feel even more like a hack to me (even though it's a workable one)

[neild]

Adding the interface makes it simple to implement a middleware because it is immediately clear what is needed (i.e., a type implementing that single Do function).

Please note that an *http.Client has four exported fields and six methods. If you want a single-function interface, http.RoundTripper is exactly that.

That said, if you want to set an Authorization header, then this generally should not be done in a RoundTripper. *http.Client adds support for redirect following, and strips sensitive headers like Authorization when following cross-domain redirects. If a RoundTripper adds an Authorization header, that header may be improperly sent after following a redirect.

If you want a way to add headers to outbound requests, then either a client interface or a request-modifying function seem reasonable.

[findleyr]

At this point, maybe we should keep the *http.Client and add a request-modifying option. That seems to solve the problem in a (mostly) orthogonal and entirely backward-compatible way.

[manuelibar]

Thank you all for taking the time to review and discuss this proposal. I really appreciate the thoughtful feedback. After carefully considering your points, I'd like to present additional evidence and clarify why this interface would benefit the MCP SDK's adoption in enterprise environments.

Existing examples

@jba: You're absolutely right that my initial examples were inaccurate. After further research, here are concrete examples from reputable Go libraries:

• AWS SDK for Go v2 defines an HTTPClient interface
• Gojek's Heimdall explicitly uses a Doer interface for the same purpose, documenting this as a deliberate design choice for flexibility.

Although, I must admit, most of the cases I encountered are, in fact, using *http.Client struct 🤔 (makes me wonder why, to be honest)

---

@neild

What behavior do you want to add or modify that can't be provided in RoundTripper?
Thank you for this question - it helped clarify the real issue. You actually highlighted a critical point when you noted that Authorization headers shouldn't be added in RoundTripper due to security concerns with cross-domain redirects. This exemplifies the broader challenge: RoundTripper operates at the wrong abstraction level for many enterprise requirements.

Application-Level vs Transport-Level Concerns

Enterprise environments typically have standardized HTTP clients that handle application-level concerns:

Application-Level (HTTP Client):

• OAuth2 token lifecycle management (refresh, rotation, caching)
• Circuit breakers with business-logic-aware fallbacks
• Request/response auditing with PII redaction policies
• Distributed tracing context propagation (OpenTelemetry)
• API rate limiting with quota management
• Request signing (AWS Signature V4, custom schemes)
• Retry strategies with business-aware backoff
• Cookie jar management with security policies

Transport-Level (RoundTripper):

• Connection pooling
• HTTP/2 negotiation
• TLS configuration
• DNS resolution
• Keep-alive settings
• Proxy configuration

The distinction matters because most organizations already have battle-tested HTTP client implementations encapsulating these application-level concerns. Forcing teams to extract and reimplement this logic as RoundTripper middleware means:

1. Duplicating complex, tested code
2. Potentially introducing bugs in critical paths
3. Breaking established patterns and tooling
4. Increasing maintenance burden

Developer Experience

As @fgrosse noted, the Do(*http.Request) (*http.Response, error) interface is immediately recognizable to any Go developer. In contrast, RoundTripper feels like an implementation detail of http.Client that many developers aren't familiar with.

Testing and Mocking

The interface approach significantly improves testability:

// With interface - clear and simple
type mockClient struct {
    DoFunc func(req *http.Request) (*http.Response, error)
}
func (m *mockClient) Do(req *http.Request) (*http.Response, error) {
    return m.DoFunc(req)
}

// vs RoundTripper - less intuitive
type mockTransport struct {}
func (m *mockTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    // Now I need to understand RoundTripper semantics
}

The Pragmatic Question: What's the Harm?

I believe this is the most important question. I respectfully suggest that the question shouldn't be "why?" but rather "why not?" - especially when it makes the SDK more flexible at zero cost. This change:
✅ Is non-breaking - *http.Client already implements this interface
✅ Has zero runtime cost - it's a compile-time abstraction
✅ Follows Go idioms - "accept interfaces, return structs"
✅ Improves composability - users can still use RoundTripper if preferred, is not a matter of chosing one or the other.
✅ Enhances testability - mocking becomes straightforward
✅ Increases adoption - reduces friction for developers

The alternative suggested by @findleyr of adding a request-modifying function only addresses the header injection use case, not the broader integration challenges some organizations face.

Thank you again for your time and consideration in reviewing this proposal 🙌

[jba]

That said, if you want to set an Authorization header, then this generally should not be done in a RoundTripper.

@neild, does that mean that this RoundTripper is incorrect?

[jba]

Application-Level (HTTP Client):

• OAuth2 token lifecycle management (refresh, rotation, caching)

https://pkg.go.dev/golang.org/x/oauth2 seems to handle this without a Client interface.

• Distributed tracing context propagation (OpenTelemetry)

Ditto.

• Cookie jar management with security policies

net/http.CookieJar is an interface. You can set it on an http.Client.

• Circuit breakers with business-logic-aware fallbacks
• Retry strategies with business-aware backoff
• API rate limiting with quota management

I don't see offhand why a RoundTripper can't do these.

• Request/response auditing with PII redaction policies
• Request signing (AWS Signature V4, custom schemes)

These, along wth adding headers, suggests that we add a function with signature

func(*http.Request) *httpRequest

[fgrosse]

At this point, maybe we should keep the *http.Client and add a request-modifying option. That seems to solve the problem in a (mostly) orthogonal and entirely backward-compatible way.

While this works, it isn't the best UI for such a common use case (e.g., authorization).

I know it's yet another change, but now is still the time to do this before v1? Given we are changing a concrete type for an interface, most existing users' code would continue to work without modifications - at least the ones who only assign a new *http.Client to the StreamableClientTransport.HTTPClient or SSEClientTransport.HTTPClient field.

IMHO using an interface is definitely preferable to a function option because users can always provide a function implementation of an interface. However, connecting a struct to a function (closure) is possible, but more complex than the other way around.