kotlin-sdk/samples/kotlinlang-mcp-server

Kotlinlang MCP Server

A Streamable HTTP MCP server that exposes the official Kotlin documentation to LLM clients — full-text search via Algolia plus page retrieval in markdown through kotlinlang.org's _llms endpoints.

Overview

This sample demonstrates an MCP server that wraps a real external documentation source. It uses the recommended Streamable HTTP transport, supports multiple concurrent client sessions, and caches responses in memory to reduce upstream load. The server is intentionally read-only — it exposes two tools, no prompts, no resources.

Prerequisites

• JDK 21+
• Algolia credentials for kotlinlang.org (exported as environment variables, see Configuration)

Build & Run

export ALGOLIA_APP_ID=...
export ALGOLIA_API_KEY=...
export ALGOLIA_INDEX_NAME=...

./gradlew run

The server starts on http://localhost:8080/mcp by default.

Connect with the MCP Inspector:

npx @modelcontextprotocol/inspector

In the Inspector UI, select Streamable HTTP transport and enter http://localhost:8080/mcp.

MCP Capabilities

Tools

Name	Description
search_kotlinlang	Full-text search across Kotlin documentation. Returns up to 5 results filtered to /docs/ pages. Responses cached for 10 minutes.
get_kotlinlang_page	Fetches a documentation page as markdown via kotlinlang.org's _llms endpoint. Accepts a path relative to /docs/. Cached for 1 hour.

Example paths accepted by get_kotlinlang_page: coroutines-overview, multiplatform/compose-multiplatform-and-jetpack-compose. Leading/trailing slashes and an optional .html suffix are normalized before resolution.

Configuration

Variable	Required	Default	Description
ALGOLIA_APP_ID	yes	—	Algolia application ID
ALGOLIA_API_KEY	yes	—	Algolia search API key
ALGOLIA_INDEX_NAME	yes	—	Algolia index name
SERVER_PORT	no	8080	HTTP server port
SERVER_HOST	no	0.0.0.0	HTTP server bind address

The server does not provide fallback values for ALGOLIA_*. Startup fails if any of those variables are missing.

Docker

Multi-stage build with Alpine-based images. Runs as a non-root user.

docker build -t kotlinlang-mcp-server .

docker run \
  -p 8080:8080 \
  -e ALGOLIA_APP_ID=... \
  -e ALGOLIA_API_KEY=... \
  -e ALGOLIA_INDEX_NAME=... \
  kotlinlang-mcp-server

Connecting an MCP client

Any MCP client that supports Streamable HTTP transport can connect:

{
  "mcpServers": {
    "kotlinlang": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Limitations

This sample is intended for demonstration only. Before production use, consider:

• In-memory cache only — cached data is lost on server restart.
• No authentication or authorization — run behind a trusted proxy or restrict network access.
• No rate limiting on outgoing requests to Algolia and kotlinlang.org.
• Permissive CORS (anyHost()) — restrict to specific origins for any non-local deployment.
• Streamable HTTP only — no STDIO transport for local-only usage.
• Tools only — no MCP resources or prompts are exposed.