MCP Mediator

MCP Mediator – Automatic MCP Server Generation

A Java-based implementation of a Model Context Protocol (MCP) mediator that automatically generates an MCP Server from existing source code, service classes, helper methods, and external MCP tools. The MCP Mediator aggregates these diverse components into a unified MCP Server, streamlining communication between MCP clients and servers through a single point.

By eliminating the need to manually maintain multiple MCP Servers, this tool simplifies integration and execution within the MCP ecosystem and make it possible to generate MCP Servers without altering the existing code bases and tools that are planned to be MCP compatible.

Overview

The MCP Mediator implements the Model Context Protocol specification, providing a robust framework for:

• Handling MCP requests and responses
• Managing tool execution
• Supporting various transport mechanisms
• Integrating with Spring Framework and Spring Boot

For more information, visit the project's wiki: MCP Mediator Wiki. Wiki page is organized as follows:

• Getting Started
• Basic Usage
• Configuration
• Components

Features

• Support for stdio/sse transport
• Extensible request handling system
• Configurable server capabilities
• Support for multiple tool implementations
• Support for proxying multiple MCP servers
• Automatically generating MCP Server Tools for the existing methods and services
• Spring Framework and Spring Boot integration
• Comprehensive error handlin
• Docker Implementation
• Dropbox Implementation
• Generate MCP Server for existing Spring Controllers and mediate request between MCP client and controllers
• Generate MCP Server for existing OpenAPI specification and generate MCP Tool for the APIs and delegate the requests

Modules

• mcp-mediator-api: Core API interfaces and contracts
• mcp-mediator-core: Core implementation and common functionality
• mcp-mediator-commons: Reusable components to make implementation easier
• mcp-mediator-security: Generic security context and thread propagation for non-Spring projects
• mcp-mediator-spring: Spring Framework and Spring AI integration
• mcp-mediator-spring-security: Bridges the mediator seamlessly into Spring Security's native SecurityContextHolder
• mcp-mediator-spring-boot-starter: Spring Boot autoconfiguration to generate MCP server automatically for the available endpoints
• mcp-mediator-openapi: Translates OpenAPI specifications directly into MCP tool endpoints
• mcp-mediator-inspector: Utilities for inspecting and debugging Mediator state
• mcp-mediator-example: Example shows how to use and extend the mediator framework
• Implementation modules for various services:
  • mcp-mediator-implementation-docker: Docker service integration Read More
  • mcp-mediator-implementation-dropbox: Dropbox service integration (WIP)
  • mcp-mediator-implementation-query: Query services with public APIs: List of all Query MCP Servers

Getting Started

Prerequisites

• Java 17 or later
• Maven 3.6 or later
• Spring Boot 3.2.2 or later (for Spring Boot integration)

All the examples are available under mcp-mediator-exmple module. It's still a work in progress and the examples will be added.

Default MCP Mediator

To create a MCP Mediator with STDIO transport:

DefaultMcpMediator mediator = new DefaultMcpMediator(McpMediatorConfigurationBuilder.builder()
          .createDefault()
          .serverName(MY_EXAMPLE_MCP_SERVER_STDIO)
          .build());
mediator.registerHandler(new WikipediaQueryRequestHandler());
mediator.initialize();

To run the examples as Claude Desktop MCP Server:

{
  "mcpServers": {
    "my_java_mcp_server": {
      "command": "[path to]/run.sh",
      "args": [
        "DefaultMcpMediatorStdioExample"
      ]
    }
  }
}

This config runs DefaultMcpMediatorStdioExample sa STDIO MCP server. Make sure to make run.sh executable and add mvn command to your path.

 ./run.sh ClassName [arg1 arg2 ...]

This mediator runs a STDIO MCP server with handlers and delegates requests from MCP client (e.g. Claude Desktop) to the registered handlers.

Convert Existing Code to MCP Server

Convert the existing code, service, helper class, or method automatically to an MCP server using @McpService:

DefaultMcpMediator mediator = new DefaultMcpMediator(McpMediatorConfigurationBuilder.builder()
                .createDefault()
                .serverName(MY_EXAMPLE_MCP_SERVER_STDIO)
                .serverVersion("1.0.0.0")
                .build());
// DockerClientService is an existing service class to interact with the installed Docker Client
        mediator.registerHandler(McpServiceFactory.create(new DockerClientService(dockerClient))
                .createForNonAnnotatedMethods(false)
                .build());
        mediator.initialize();

DockerClientService:

@McpService(name = "docker_mcp_server",  description = "provides common docker command as mcp tools")
public class DockerClientService {

    DockerClient internalClient;

    @McpTool(name = "docker_start_container",
            description = "start an existing docker container using its containerId! containerId is required and " +
                    "can't be null or empty! if successful, returns true.")
    public boolean startContainerCmd(@NonNull String containerId) {
        internalClient.startContainerCmd(containerId)
                .exec();
        return true;
    }
    // ...
}

Checkout mcp-mediator-implementation-docker for more details.

Proxy MCP Mediator

To create a proxy server:

 // as an example ~/sdk/jdk/jdk-17.0.14+7/Contents/Home/bin/java
String command = args[0];
// e.g., -jar ~/mcp-mediator-example.jar
List<String> remoteServerArgs = List.of(Arrays.copyOfRange(args, 1, args.length));

ProxyMcpMediator mediator = new ProxyMcpMediator(McpMediatorConfigurationBuilder.builder()
       .creatProxy()
       .serializer(new ObjectMapper())
       .tools(true)
       .addRemoteServer(McpMediatorProxyConfiguration.McpMediatorRemoteMcpServerConfiguration.builder()
               .remoteTransportType(McpTransportType.STDIO)
               .remoteServerAddress(command)
               .remoteServerArgs(remoteServerArgs)
               .build())
       .serverName(MY_EXAMPLE_MCP_SERVER_STDIO)
       .serverVersion("1.0.0.0")
       .build());

mediator.initialize();

This mediator creates a Proxy MCP server and connects to all the given remote servers and works as a proxy between the client and the remote servers. The mediator will advertise all the available Tools to the clients during the initialization process. It is also expandable by registering request handlers using ProxyMcpMediator#registerHandler() same as DefaultMcpMediator.

Implemented Query MCP Servers

Query MCP servers are MCP servers that receive a query from the user and search a source for the content related to the input query. All the queries are part of mcp-mediator-implementation-query module and are defined using MCP Mediator Request Handlers. So far, these queries are implemented:

• Wikipedia MCP Server: Search Wikipedia with an input query
• Stackoverflow MCP Server: Search Stackoverflow website
• GitHub MCP Server: Search for GitHub projects

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Read this first!

License

This project is licensed under the GPL3 License - see the LICENSE file for details.

Security & Authorization

MCP Mediator supports native integration with authorization frameworks, including Spring Security. Since MCP requests (especially over STDIO) rely purely on JSON payloads, you can use the McpMediatorInterceptor to extract tokens from the arguments payload and bridge them into your security context.

We provide two dedicated modules for this:

• mcp-mediator-security: Generic security context and thread propagation for non-Spring projects.
• mcp-mediator-spring-security: Bridges the mediator seamlessly into Spring Security's native SecurityContextHolder.

For complete implementation details and code examples, please check out the Security Integration Guide in the Wiki, or refer to GenericSecurityExample and SpringSecurityExample in the mcp-mediator-example module.

Observability & Error Handling Examples

The mcp-mediator-example module includes dedicated examples demonstrating how to fully instrument the Mediator:

• ObservabilityExample: Shows how to programmatically inject an OpenTelemetry instance to export traces (via OTLP for Datadog or LoggingSpanExporter for standard SLF4J logs).
• CustomErrorHandlerExample: Demonstrates customizing the McpMediatorExceptionHandler to intercept execution errors, route them through an SLF4J logger, and return safe, obfuscated fallback strings to the client without exposing internal Java stack traces.