Why is the Java SDK not generic ?

[sebastienblanc]

Pre-submission Checklist

• I have verified that this discussion would not be more appropriate as an issue in a specific repository
• I have searched existing discussions to avoid duplicates

Discussion Topic

The current MCP Java SDK is implemented on top of an existing Framework (Spring). While I'm sure it's an excellent implementation and it's not generic enough for people that would like to use it outside of Spring.
Other stacks like Quarkus and Langchain4j also provide solid implementations (both client and server side). Until a generic SDK is released maybe those implementations could also be mentioned in the modelcontextprotocol ?

[lordofthejars]

Actually, probably the best approach would be to do something like we used to do in Java in the past: create an SPI, and then everyone provides its own implementation on top of that. It can be an RI implementation, which can be Spring Boot, plain Java, or Vertex, but at least having an SDK is not tight to anything.

[edeandrea]

Totally agreed, and this is the position something like LangChain4j has adopted. Written in plain Java with SPIs that allow extension.

[orpiske]

Big +1 for this. There are, IMHO, significant advantages to providing an SPI and letting projects provide their own implementation: projects can evolve independently at their own pace.

[shane-orourke]

Agree with the comments above. Why would we contain to a single implementation particularly since the wide adoption of LangChain4J.

[noear]

agree!

[renatomarinho]

Interesting discussion! As the founder of GitScrum, I've been working on an MCP server implementation for project management integration. I'd love to get feedback from the community on our approach.

We built GitScrum MCP Server (open source) to connect project management workflows with Claude through the Model Context Protocol. It handles tasks, sprints, and team collaboration directly via AI interactions.

GitHub: https://github.com/gitscrum-core/mcp-server

Would appreciate your thoughts and suggestions on the implementation! What features would be most valuable for your use cases?

[sivaprasadreddy]

It looks like MCP is going to stay and grow in the future. In that case, it would be great to have an SPI which is not coupled with any specific framework. That would allow any Java/JVM based applications to leverage MCP capabilities relying on SPI.

[tzolov]

@sebastienblanc,

The current MCP Java SDK is implemented on top of an existing Framework (Spring).

This statement is incorrect. The core mcp module is framework-agnostic, providing STDIO and SSE client/server transports (SSE server transport uses Servlet spec). You can build MCP clients/servers with plain Java using the core mcp dependency, with both async (project reactor) and sync APIs available.

The mcp-spring is optional and only necessary if you're using Spring's WebMVC/Webflux web server support. Don't use it if you're not using Spring.

Other frameworks can contribute optional transport implementations for their frameworks on top of the core mcp module.

We have to update the documentation to clarify the distinction between core mcp and optional mcp-spring modules.

[maxandersen]

@edeandrea we don't have to get into asking for justification based on numbers or popularity ratings. What we can just say is that Java ecosystem is big and it is a age old issue with java that things like http clients and reactive/async paradigms was standardized late - but thats just the reality we have to live with.

And from that perspective I agree that it would be great to explore how to at least avoid the default MCP Java SDK ties itself to specific implementations.

I would like to see the proposed PR from @tzolov as parts of it at least sounds like it will move things to JDK API's - but lets see.

[jponge]

Thanks for the feedback @tzolov

I unfortunately have to disagree from a technical point of view on several points.

I'm posting this feedback to provide perspective on the discussion to the community, not to win an argument.

Reactive Streams was created as an interoperable standard for reactive implementations. Every Mono or Flux returned by the SDK’s API implements RS Publisher and can be easily adapted to a corresponding type, including the JDK 9 Flow.Publisher. This specification has been around for a decade — it’s neither legacy nor obsolete. The most popular implementations (RxJava, Project Reactor, Akka Streams) are based on the reactive-streams-jvm interfaces, are widely used in production and have gained stability over the years. We do appreciate the fact that these interfaces were incorporated into the JDK under the java.util.concurrent.Flow subinterfaces, however these bring no added value for the tremendous migration efforts for users. The Flow types have not been widely adopted in the JDK and there are no operator implementations to take advantage of. We don’t think SPIs are well suited for abstracting reactive pipelines.

A few observations:

• reactive-streams-jvm was a set of operator implementations for the original reactive stream APIs, not a set of interfaces. It then drove some internals of RxJava 2 / Reactor (which have had lots of cross-pollinisation).
• There is no "tremendous" migration effort to migrate to the JDK Flow APIs. We did it a few years ago. End-users are shielded from using direct publisher types by higher-level libraries (Mutiny, RxJava, Reactor). Reactive streams is a low-level protocol for back-pressured async I/O streams. Version 2.0 of Mutiny coincided with a migration from the old Reactive Streams APIs to Java Flow, and it was transparent for end-users. It would be the same if, say, RxJava migrated to Flow. The impact is mostly on frameworks / client driver providers, but as you said there are adapters, so...
• Mono being a reactive streams publisher is an implementation detail, especially as one async operation is not a stream and does not justify the protocol overhead. I know some people had unsuccessfully tried to bend the Reactive Streams TCK for that specific case, but the community behind the TCK always pushed back on the idea.

In the MCP Java SDK, we currently accept a Function<Mono<T>, Mono<T>>, which goes against the best practices. This week, we’ll submit a PR to change this to Function<Publisher<T>, Publisher<T>> where applicable to ease interoperability.

From an external consumption point-of-view this is an interesting step in the right direction, but again, Publisher is for streams. If you model 1-shot asynchronous operations then it does not make sense to return a Publisher (but I get that it simplifies the Spring cases because Mono is a Publisher while it streams at most one element).

Converting between RS Publisher and Flow.Publisher is straightforward with the help of Reactor’s JdkFlowAdapter.

The Reactive Streams APIs provide adapters, and so does Mutiny Zero. It's never been an issue to go back and forth the APIs (hence it's not a "tremendous" migration effort).

Replacing Mono with the JDK’s CompletableFuture introduces several drawbacks. While CompletableFuture supports non-blocking behavior and composition, it lacks key features of reactive streams — most notably built-in backpressure. We would also lose important capabilities such as end-to-end cancellation, retries, consistent error handling, lazy execution, and the rich set of operators available to both developers and users.

• You are probably confusing CompletableFuture and CompletionStage. The latter is what any vendor-neutral library would provide as one-shot async operation abstraction.
• You can use CompletionStage directly as a user, but you can also plug into into a richer API like Mutiny, Reactor, RxJava, etc, where a consistent error-handling / cancellation is possible.

Also CompletionStage does not support back-pressure... yes, just like Mono doesn't. Back-pressure signaling exists only for streams.

Additionally, CompletableFuture runs by default (for async operations) on the ForkJoinPool, which cannot be customized, making context propagation via ThreadLocal or functional constructs difficult. In contrast, Project Reactor’s optional Context integration with Micrometer allows us to incorporate observability features into the SDK in the future.

Again, your target for vendor-neutral interop is CompletionStage. An interface.

There are multiple async context APIs around, so tying the SDK to one is likely going to be a problem outside of Spring.

Another reason for choosing Reactive Streams as the asynchronous core is to support streaming capabilities in the MCP protocol. A reactive foundation enables us to seamlessly combine APIs that return Mono with those that expose Flux for stream processing.

If you have CompletionStage and Flow.Publisher (or Publisher) then you have the built-ins for any other Java ecosystem to provide its sound integration. Async I/O + Back-pressured Async I/O streams. Mono / Flux is one of them, Uni / Multi is another one.

Once the upcoming PR is merged, the following code snippets demonstrate how Mutiny can interoperate easily with the MCP API:

    // Using API that returns Mono (an RS Publisher)
    Tool tool = new McpSchema.Tool("Tool name", "Description", schema);
    var mcpAsyncServer = McpServer.async(createMcpTransportProvider())
        .serverInfo("test-server", "1.0.0")
        .capabilities(ServerCapabilities.builder().tools(true).build())
        .tool(tool, (exchange, args) -> {
            Uni<CallToolResult> uniItem =
                Uni.createFrom().item(new CallToolResult(List.of(), false));
            Flow.Publisher<CallToolResult> flowItem =
                uniItem.convert().toPublisher();
            return Mono.from(JdkFlowAdapter.flowPublisherToFlux(flowItem));
        }).build();

    // Using API that accepts RS Publisher:
    McpClientTransport transport = createMcpTransport();
    transport.connect(messages -> {
        Flow.Publisher<McpSchema.JSONRPCMessage> flowPublisher =
            JdkFlowAdapter.publisherToFlowPublisher(messages);
        Uni<T> uni = Uni.createFrom()
                        .publisher(flowPublisher)
                        .onItem()
                        .invoke(() -> System.out.println("processing item"));
        return uni.convert().toPublisher();
    }).subscribe();

Thanks for trying this out!

Just so you know, Mutiny offers a simpler way to go from Reactor to Mutiny and back: https://github.com/smallrye/smallrye-mutiny/tree/main/reactor (there is also a module for the RxJava 3 interop).

[dsp-ant]

@jponge Let's assume the use of Reactor as the default here won't change. What exact changes are you proposing to the SDK to make it compatible with other libraries? Do you mind working on a set of somewhat digestible PRs towards that?

[jponge]

@dsp-ant It's not about compatibility per-se, and @tzolov provided a sound snippet + a possible API change where there one could use the API from another reactive programming library.

The problem with Reactor as a default is that this is a too opinionated implementation (API, assumptions, context propagation, etc) while the standard Java library already provides imperfect, yet vendor-neutral APIs from which frameworks can perform their integration.

The problem would have been the same if someone came up with a "standard MCP Java library" and wrote it with Mutiny, Vert.x and Netty.

[lordofthejars]

To sum up, if you want to provide any standard API, then the SPI/API part of the project should have no external dependency (ideally). And then of course, you can have a reference implementation of different implementations, but if you have any external dependency on your management system then, it is not exactly a generic/standard project.

[dsp-ant]

Jumping in here. I can't talk to the specifics, since I don't know the Java ecosystem enough to have a well formed opinion. I just want to be mindful that we keep the discussion productive and work towards what is clearly a good goal: A Java SDK core that everyone in the ecosystem can build on top.

I can't speak for @tzolov, who of course is the maintainer of the SDK, but I would want to encourage people to build out the necessary infrastructure in the SDK together. This can be in whatever form @tzolov prefers, be it PRs, RFCs, etc.

I'd strongly prefer if one or two people from the different interest groups, e.g. quarkus, represent the needs of the project and we don't continue to pile onto the thread.

[maxandersen]

@dsp-ant yes, we are after the same thing - but if the core SDK will continue enforcing a hard dependency on a specific async implementation rather than one that can be used more broad it will be a challenge to have something that everyone in the ecosystem can build on top.

I and others in Quarkus happy to work with @tzolov on how we can get to something that is broader applicable.

One thing we already from early days wanted to explore was the declarative API where we would use Java Annotations like @tools, @prompts, etc. similar to how JAX-RS and JPA specs define a vendor neutral way to handle REST based endpoints while still allow to have vendor/library/framework specific improvements for it.

We planned to extract that from work in Quarkus, WildFly and others and happy to contribute that to modelcontextprotocol org.

For the client it can be more challenging but lets see what comes from the experimentation we all are doing in realtime with MCP at the moment :)

p.s. @dsp-ant check your messages from Feb 14th where I pinged on this too :)

[tzolov]

We have identified a reasonable way to introduce an implementation-neutral SPI module that will allow any vendor to provide its own implementation without too much disruption. For the Reactive part, we are going to follow the R2DBC "playbook" which has proven to be successful in building a healthy ecosystem. So in practice we are likely going to introduce an mcp-spi module with no dependency on Reactor which any implementor can use to provide their implementation.

On the technical side, we don't consider CompletionStage as a suitable type to expose mainly due to the eager processing and cancellation behavior it involves, so we’ll use Publisher for single async values with some related documentation for implementers like we successfully did in R2DBC.

For the Publisher variant, our opinion (we acknowledge Red Hat contributors have a different one, and that's ok) is that the RS Publisher is the abstraction we prefer to continue using for multiple reasons. The JDK team seems more interested in investing in Virtual Threads and Structured Concurrency than leveraging Flow interfaces outside of the HTTP client, the TCK still lives on reactive-streams.org side, so in the meantime the Reactive Streams variant of Publisher is maybe not the worst bet for the future. Also, an entire multi-stakeholder reactive ecosystem (R2DBC, RSocket, large companies like Netflix and Amazon) outside of Red Hat is built on the org.reactivestreams variant, so that’s a pretty large target audience for this SPI, and that would allow us to propose a JDK 8 baseline for the SPI in case some companies want to provide such implementation. There would be no practical gain in replacing this widely established contract—only significant pain due to its integration in countless libraries throughout the ecosystem. Finally, it is very easy to adapt to/from RS Publisher to the JDK Flow variant.

For declarative APIs, we think that's far too early for standardizing anything, even just annotations, but we can of course begin to discuss and brainstorm.

[edburns]

Hi @edburns wouldn't the Java 8 conversation be relevant here since the Flow API didn't exist until Java 9?

This is true. However, there are so many other aspects of the "Should the official Antropic Java SDK for MCP support Java 8", I judge it warrants its own thread (#322)

[edburns]

streams api can use : org.reactivestreams:reactive-streams

I assert that this approach would require an adapter of some kind. Are you suggesting that the SPI proposed by @tzolov in this thread include such a self-contained adapter?

Please correct me if my assertion is false.

[noear]

@edburns reactivestreams is a bit more general, and the most popular reactive frameworks are based on reactivestreams

[edburns]

Thanks @noear . I acknowledge your statement of popularity. However, I maintain that following that approach alone would amount to tacet acceptance of de-facto standards being the only kind of standards. Personally, I have seen significant and influential customer testimonial in my many years in the Java community to not tacitly accept that.

Do you have any other supporting arguments other than a subjective statement of "it's the most popular"?

[jponge]

Just so people realize: the JDK Flow API is Reactive Streams, and for a very long time the Reactive Streams API / TCK has had a Flow variant (see https://github.com/reactive-streams/reactive-streams-jvm/blob/master/tck-flow/README.md), because, well... people were expected to move to the JDK API and drop the original Reactive Streams library.

[noear]

I hope it supports jdk8! There are plenty of production jdk8 environments out there, and they're afraid to upgrade.

[noear]

@geoand spring is based on java17 because of the java-ee package name change

[noear]

@geoand As a base framework, if not directly using the java-ee interface. It is compatible with java8 to java24 at the same time

[geoand]

spring is based on java17 because of the java-ee package name change

@sdeleuze can answer authoritatively, but I am pretty certain this is not the reason Spring Framework, Spring Boot and everything built on top are now Java 17+.

[noear]

@geoand I also hope everyone upgrades to java 21. I can use the new syntactic sugar:)

[edburns]

I kindly request all JDK 8 related matters be discussed at #322.

[edburns]

At the outset, @sebastienblanc wrote:

Until a generic SDK is released maybe those implementations could also be mentioned in the modelcontextprotocol ?

I did seek to mention them at least in modelcontextprotocol/servers#758 . Perhaps I can get some upvotes on that one?

[edeandrea]

So what ever happened here? I see now that on https://modelcontextprotocol.io/sdk/java/mcp-server#sse-servlet the SSE (Servlet) approach is completely tied to Spring....

That doesn't seem at all right. Even if its just in the documentation, when presenting an example of a "vanilla" integration, the example should be "vanilla".

[lordofthejars]

Actually, it is tied to Servlet, but the example is with Spring; they state that with any Servlet container, it should work, but I think docs should tackle this scenario, and not the Spring one.

[scottslewis]

I have started a dev community effort/project to create 'generic MCP apis' implemented in Java.

I am engaged with the spring team and Quarkus team to solicit their participation and contribution in this community-driven effort. I'm looking for the broadest participation possible.

The goals are to

1. Create stable, high-quality, open, spec-compliant, maintained Java APIs and Tools for MCP server and client development

2. To the extent possible, compatibility with existing frameworks and working implementations using those frameworks

3. Governance by the participating dev community rather than any commercial or non-commercial entity

[tzolov]

Hi Scott, happy to collaborate with you, as we are already doing on merging/refining your OSGi compatibility contribution, but we are not convinced that creating a distinct organization that looks like a reimplementation from scratch is the best way to collaborate. Maybe you should instead start with https://github.com/spring-ai-community/mcp-annotations and provide feedback on what you would like to see done differently, compare it with other framework approaches, identify what is missing, etc.

For other topics, we are going to share shortly a related update where there will be plenty of opportunities for collaboration.

[edeandrea]

I think what Scott (& others) are proposing is a vendor-neutral SDK that is not tied to project reactor (or anything to do with Spring). Even the getting started guides for the Java MCP SDK are for "Spring only".

Its fine if Spring AI would like to donate its original implementation, but to be considered a "generic" SDK, it needs to truly be generic.

Even saying

Maybe you should instead start with https://github.com/spring-ai-community/mcp-annotations and provide feedback

Is saying that "Spring AI is the only way to do this". What we (& others in the community) would like is a generic SDK that is vendor-neutral that anyone can build on top of.

[sdeleuze]

@edeandrea See my update below.

[scottslewis]

Hi Scott, happy to collaborate with you, as we are already doing on merging/refining your OSGi compatibility contribution, but we are not convinced that creating a distinct organization that looks like a reimplementation from scratch is the best way to collaborate.

I agree that creating a re-implementation from scratch is not the best way to collaborate.

That is explicitly not what's intended or being done with OpenMCPTools. Creating a new github organization is something I, as a dev community member and experienced open source project lead can do.

What's being done with OpenMCPTools is to create generic APIs (as per this issue) that are distinct from any/all framework, created (hopefully) with collaborative participation from all interested and qualified developers...including (ideally) everyone that's reading this, as full participants in the API creation/definition.

Then making these APIs available to the broader dev community in whatever way the community dictates. What are some possibilities here:

1. Any/all of what's done in this org could be contributed to the MCP Java SDK project at some point
2. Could be contributed to a new or existing LF or other oss org project
3. Could be contributed to some other new'standards' org
4. Could be contributed directly to the dev community from OpenMCPTools...as a dev community managed project

My point is this: This project's output (framework-independent APIs) can/will be contributed to other projects (e.g. the MCP Java SDK project) as decided by the dev community (the consumers of SDKs).

A short example of what I'm talking about:

There has been/is much discussion in MCP-land about adding support for MCP server-defined groups/grouping.

I've designed an experimental and publicly incubating Java API for primitive grouping.

I've implemented this API using the MCP Java SDK with a MCP extension.

Here's is a working prototype app built on these components with server-defined toolgroups. This impl of these APIs depends upon/uses the MCP Java SDK and mcp-annotations.

My point here is: I will be thrilled to contribute these APIs to existing projects (e.g. the MCP Java SDK project or others as described above) if desired by the interested developer community...once the APIs are out of the experimental/incubation/design phase.

Maybe you should instead start with https://github.com/spring-ai-community/mcp-annotations and provide feedback on what you would like to see done differently, compare it with other framework approaches, identify what is missing, etc.

I have already done that, but as described above I would be very happy to contribute things like this grouping work...which does use mcp-annotations for the spring impl

For other topics, we are going to share shortly a related update where there will be plenty of opportunities for collaboration.

That's wonderful. You will likely find me offering to contribute/collaborate/communicate, as long as I am able. This/OpenMCPTools is not a competitive project or framework. Please consider thinking of it as a framework-agnostic API incubator, not just for the Java SDK, btw.

[sdeleuze]

I would like to share a roadmap update that we have discussed with the MCP Java SDK team and that should help making the MCP Java SDK more generic:

• java-sdk#778 shares the intent of introducing a unified Virtual Threads friendly API that should provide a more generic and flexible design
• The Spring-specific parts of the MCP SDK are going to be moved from https://github.com/modelcontextprotocol/java-sdk/tree/main/mcp-spring to https://github.com/spring-projects/spring-ai via spring-ai#5423
• Thanks to the collaboration with the Micronaut team, the JSON support is now pluggable and we have 2 implementations (Jackson 2 and Jackson 3)

[edeandrea]

Thank you @sdeleuze for the update!