MCP Development

This section covers how to develop custom MCP (Model Context Protocol) protocol plugins to extend Astrsomn's context management capabilities.

Overview

MCP plugins handle transport protocols between the AI model and external MCP services. Astrsomn uses the McpProtocolHandler interface to support multiple transport types.

Important

The McpHandler interface referenced in older documentation does not exist. The actual interface is McpProtocolHandler, located at com.astrsomn.starter.runtime.langchain.tool.mcp.protocol.

Built-in Protocol Implementations

Implementation	Protocol	Description
SseProtocolHandler	SSE	HTTP Server-Sent Events based MCP transport
StdioProtocolHandler	STDIO	Subprocess stdin/stdout based MCP transport

Development Steps

1. Create Maven Module

<project>
    <groupId>com.astrsomn</groupId>
    <artifactId>astrsomn-mcp-custom</artifactId>
    <version>0.2.0-SNAPSHOT</version>

    <dependencies>
        <dependency>
            <groupId>com.astrsomn</groupId>
            <artifactId>astrsomn-api-runtime</artifactId>
            <version>0.2.0-SNAPSHOT</version>
        </dependency>

        <!-- LangChain4j MCP support -->
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-mcp</artifactId>
        </dependency>
    </dependencies>
</project>

2. Implement McpProtocolHandler

McpProtocolHandler has only two methods: supports() checks transport type compatibility, createTransport() builds the transport instance:

package com.astrsomn.mcp.custom;

import com.astrsomn.api.runtime.common.entity.AiMcpEntity;
import com.astrsomn.starter.runtime.langchain.tool.mcp.protocol.McpProtocolHandler;
import dev.langchain4j.mcp.client.transport.McpTransport;

import java.io.IOException;

public class CustomMcpProtocolHandler implements McpProtocolHandler {

    @Override
    public boolean supports(String type) {
        // Check if this handler supports the given transport type
        return "CUSTOM".equalsIgnoreCase(type);
    }

    @Override
    public McpTransport createTransport(AiMcpEntity config) throws IOException {
        // Build an McpTransport from configuration
        // config contains MCP server connection parameters (address, port, auth, etc.)

        String address = config.getAddress();
        int port = config.getPort();

        return new CustomWebSocketMcpTransport(address, port);
    }
}

McpTransport

McpTransport is LangChain4j's MCP client transport interface. Implement it to define your communication method (HTTP, WebSocket, gRPC, etc.). Reference LangChain4j's HttpMcpTransport and StdioMcpTransport for patterns.

3. Register SPI

Create under src/main/resources/META-INF/services/:

File: com.astrsomn.starter.runtime.langchain.tool.mcp.protocol.McpProtocolHandler

com.astrsomn.mcp.custom.CustomMcpProtocolHandler

4. Create Extension Properties (Optional)

# src/main/resources/extension-mcp-custom.properties
name=Custom MCP Protocol
version=0.2.0-SNAPSHOT
description=WebSocket-based custom MCP protocol implementation

Interface Reference

McpProtocolHandler

Package: com.astrsomn.starter.runtime.langchain.tool.mcp.protocol

Method	Return Type	Description
supports(String type)	boolean	Checks if this handler supports the given transport type
createTransport(AiMcpEntity config)	McpTransport	Creates an MCP transport from configuration

Transport Type Enum

AiMcpEnum.TypeEnum:

Type	Description
SSE	Server-Sent Events (built-in)
STDIO	Standard I/O subprocess (built-in)

Adding new types

To support a new transport type (e.g., WebSocket), first add the enum value to AiMcpEnum.TypeEnum, then implement the corresponding McpProtocolHandler.

Build & Deploy

mvn clean package -DskipTests

cp target/astrsomn-mcp-custom-0.2.0-SNAPSHOT.jar /path/to/astrsomn/plugins/

Reference Implementations

• SSE — astrsomn-runtime-starter/.../mcp/protocol/SseProtocolHandler.java — based on HttpMcpTransport
• STDIO — astrsomn-runtime-starter/.../mcp/protocol/StdioProtocolHandler.java — based on StdioMcpTransport

Related Documentation

• Interface Guide — Detailed API specifications
• Examples — Complete end-to-end examples
• Provider Development — Model provider plugin guide
• Vector Store Development — Vector store plugin guide