This module provides MCP (Model Context Protocol) server and client implementations for Kotlin. See the Model Context Protocol specification for details on the protocol and methods.

• MCP Server over HTTP: Run an MCP server that can be accessed via HTTP POST requests
• MCP Server over Stdio: Run an MCP server that communicates via standard input/output
• MCP Client: Connect to remote MCP servers via HTTP or Stdio
• Embedded Server: Run an MCP server in-memory with custom prompts and tools

• initialize - Initialize the connection with the server
• prompts/list - List all available prompts
• prompts/get - Get a specific prompt with arguments
• tools/list - List all available tools
• tools/call - Call a specific tool with arguments
• resources/list - List available resources (if supported)
• resources/read - Get a specific resource (if supported)
• resources/templates/list - List available resource templates (if supported)

You can connect to external MCP servers using the McpProviderHttp and McpProviderStdio classes.

MCP servers over Streamable HTTP are persistent HTTP servers that support client/server communications via HTTP. See https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http. Use McpProviderHttp to connect to these servers:

val provider = McpProviderHttp("http://mcp-server.example.com/mcp")
val capabilities = provider.getCapabilities()
val prompts = provider.listPrompts()
val tools = provider.listTools()
val result = provider.callTool("tool-name", mapOf("arg1" to "value1"))
val textResult = result.content.first() as McpContent.Text
println(textResult)
provider.close()

MCP servers over stdio typically function as a local process that you can launch and send/receive JSON-RPC MCP messages. Use McpProviderStdio to launch these servers locally and use them in code:

val provider = McpProviderStdio(
    command = "path/to/executable",
    args = listOf("arg1", "arg2"),
    env = mapOf("var1" to "value1", "var2" to "value2")
)
val capabilities = provider.getCapabilities()
val prompts = provider.listPrompts()
val tools = provider.listTools()
val result = provider.callTool("tool-name", mapOf("arg1" to "value1"))
val textResult = result.content.first() as McpContent.Text
println(textResult)
provider.close()

You can host your own MCP servers using the provided HTTP and Stdio server implementations. The examples here are for testing only and not intended for production use.

The default server configuration:

• Prompts: Includes research-related prompts from the PromptLibrary
• Tools: Includes tools from StarterToolLibrary
• Resources: none

To customize prompts, tools, and resources, modify the McpServerHttpMain.kt or McpServerStdioMain.kt file or create your own main class.

The MCP HTTP server supports POST requests only. It has the following configuration:

• Port: 8080 (can be customized via command-line argument)

To start an MCP HTTP server:

# Build the project first
mvn clean install

# Run the HTTP server (default port 8080)
mvn exec:java -Dexec.mainClass="tri.ai.mcp.http.McpServerHttpMainKt"

# Or specify a custom port
mvn exec:java -Dexec.mainClass="tri.ai.mcp.http.McpServerHttpMainKt" -Dexec.args="9000"

The server will start and display:

• Server URL
• MCP endpoint path
• Health check endpoint
• Number of available prompts, tools, and resources

Check if the server is running (expect response OK):

curl http://localhost:8080/health

Send an initialize request to the MCP server:

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

List available prompts:

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

Get a prompt:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "prompts/get",
    "params": {
      "name": "<prompt-name>",
      "arguments": {}
    }
  }'

List available tools:

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

Call a tool:

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "<tool-name>",
      "arguments": {
        "arg1": "value1"
      }
    }
  }'

To start the MCP Stdio server (with sample prompts and tools):

# Build the project first
mvn clean install

# Run the Stdio server
mvn exec:java -Dexec.mainClass="tri.ai.mcp.stdio.McpServerStdioMainKt"

The server will:

• Read JSON-RPC 2.0 requests from standard input (stdin)
• Write JSON-RPC 2.0 responses to standard output (stdout)
• Write server status messages to standard error (stderr)
• Display number of available prompts, tools, and resources on startup

The Stdio server can be tested by sending JSON-RPC 2.0 requests to its standard input. Here are some sample messages that can be copied directly into the input:

Initialize connection:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}

List Available Prompts:

{"jsonrpc":"2.0","id":2,"method":"prompts/list"}

List Available Tools:

{"jsonrpc":"2.0","id":3,"method":"tools/list"}

MCP Inspector is useful for testing MCP servers: https://modelcontextprotocol.io/docs/tools/inspector. Run with

npx @modelcontextprotocol/inspector <command>`

Run a test MCP server over stdio with:

npx @modelcontextprotocol/server-everything