steveo-ocheng/mcp-server-java-remote

MCP Remote Server (Java)

A remote implementation of a Model Context Protocol (MCP) server in Java using HTTP/SSE transport. This is a proof-of-concept showing how to adapt a local stdio-based MCP server to work over the network.

Key Differences from Local MCP Server

Local (stdio) Version

• Communication via stdin/stdout pipes
• Claude Desktop spawns the Java process directly
• Single client per server instance
• No network layer or authentication
• Process lifecycle managed by client

Remote (HTTP/SSE) Version

• Communication via HTTP POST and Server-Sent Events (SSE)
• Server runs independently as a web service
• Multiple concurrent clients supported
• Network-based with potential for authentication/authorization
• Server has independent lifecycle

Architecture

Transport Layer

HTTP/SSE Model:

• Client → Server: HTTP POST requests to /message endpoint
• Server → Client: Server-Sent Events via /sse endpoint
• Protocol: Same JSON-RPC 2.0 MCP messages, different transport

Components

MCPHttpServer.java - HTTP server using Javalin framework

• Manages SSE connections from clients
• Routes HTTP POST messages to request processor
• Handles multiple concurrent client sessions
• Provides health check and info endpoints

MCPRequestProcessor.java - Transport-agnostic MCP logic

• Processes JSON-RPC 2.0 requests
• Routes to tool implementations
• Same logic as stdio version, but decoupled from I/O

Tool implementations - Unchanged from local version

• CalculateTool, ReverseTextTool, WordCountTool
• Same interface and behavior

Building and Running

Build

./gradlew build

This creates build/libs/mcp-server-remote-1.0.0.jar

Run the Server

# Default port 8080
./gradlew run

# Or with custom port
java -jar build/libs/mcp-server-remote-1.0.0.jar 8081

Test the Server

Check health:

curl http://localhost:8080/health

Get server info:

curl http://localhost:8080/

Test a tool call:

curl -X POST http://localhost:8080/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "calculate",
      "arguments": {
        "operation": "add",
        "a": 5,
        "b": 3
      }
    }
  }'

Initialize session:

curl -X POST http://localhost:8080/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

List tools:

curl -X POST http://localhost:8080/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

Claude Desktop Integration

To use this remote server with Claude Desktop, you would need an MCP client that supports HTTP/SSE transport. The official MCP SDKs support this pattern.

Example configuration (conceptual - requires MCP client with SSE support):

{
  "mcpServers": {
    "mcp-server-remote-java": {
      "url": "http://localhost:8080/sse",
      "transport": "sse"
    }
  }
}

Note: The current Claude Desktop primarily supports stdio transport. This remote server is designed for:

• Custom MCP clients
• Web applications
• Microservice architectures
• Multi-tenant scenarios

API Endpoints

GET /

Server information and available endpoints

GET /health

Health check endpoint

{
  "status": "ok",
  "server": "mcp-server-remote-java",
  "version": "1.0.0",
  "activeConnections": 0
}

GET /sse

Establish Server-Sent Events connection for receiving server messages. Returns:

• connected event with client ID
• Periodic heartbeats to keep connection alive

POST /message

Send JSON-RPC 2.0 MCP messages. Accepts standard MCP methods:

• initialize - Handshake
• tools/list - List available tools
• tools/call - Execute a tool
• prompts/list - List prompts (empty)
• resources/list - List resources (empty)

Adding New Tools

Same process as local server:

1. Create a class implementing Tool interface
2. Implement getName(), getDefinition(), and execute()
3. Register in MCPRequestProcessor.registerTools()
4. Rebuild and restart server

Deployment Considerations

When deploying this server in production:

Security

• Add authentication (API keys, OAuth, JWT)
• Enable HTTPS/TLS
• Implement rate limiting
• Validate all inputs
• Add CORS restrictions for specific origins

Scalability

• Add session management for stateful tools
• Consider load balancing for horizontal scaling
• Implement connection pooling
• Add request timeouts

Monitoring

• Add metrics collection (Prometheus, etc.)
• Enhanced logging with correlation IDs
• Health check endpoints
• Performance monitoring

Configuration

• Externalize configuration (port, timeouts, etc.)
• Environment-specific settings
• Feature flags for tools

Differences Summary

Technologies Used

• Java 17 - Language runtime
• Javalin 5.6 - Lightweight web framework
• Jackson - JSON processing
• SLF4J + Logback - Logging
• Gradle - Build tool

Project Structure

my-mcp-server-java-server/
├── src/main/java/com/example/mcp/remote/
│   ├── MCPHttpServer.java        # HTTP/SSE server
│   ├── MCPRequestProcessor.java   # MCP protocol handler
│   ├── Tool.java                  # Tool interface
│   ├── ToolRegistry.java          # Tool registry
│   ├── TextContent.java           # Tool response wrapper
│   ├── CalculateTool.java         # Example tool
│   ├── ReverseTextTool.java       # Example tool
│   └── WordCountTool.java         # Example tool
├── src/main/resources/
│   └── logback.xml                # Logging configuration
├── build.gradle                   # Build configuration
├── settings.gradle                # Project settings
└── README.md                      # This file

License

This is a demonstration/educational project showing MCP protocol implementation patterns.