docs: streamable server sample (#595)

- add a simple streamable http server example with auth
- update readme: replace quickstart example from sse server to
streamable server
- add readme files for samples, simple-streamable-server, notebooks

closes #170 

## How Has This Been Tested?
knit and inspector

## Breaking Changes
NaN

## Types of changes
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update

## Checklist
- [x] I have read the [MCP
Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [ ] I have added appropriate error handling
- [x] I have added or updated documentation as needed

Author: devcrocod

.github/workflows/build.yml

@@ -180,6 +180,7 @@ jobs:
         sample:
           - kotlin-mcp-client
           - kotlin-mcp-server
+          - simple-streamable-server
           - weather-stdio-server
 
     name: "Build Sample: ${{ matrix.sample }}"

.github/workflows/samples.yml

@@ -29,6 +29,7 @@ jobs:
         sample:
           - kotlin-mcp-client
           - kotlin-mcp-server
+          - simple-streamable-server
           - weather-stdio-server
 
     name: Build Sample (${{ matrix.sample }})

README.md

@@ -21,34 +21,34 @@ standardized protocol interface.
 
 * [Overview](#overview)
 * [Installation](#installation)
-  * [Artifacts](#artifacts)
-  * [Gradle setup (JVM)](#gradle-setup-jvm)
-  * [Multiplatform](#multiplatform)
-  * [Ktor dependencies](#ktor-dependencies)
+    * [Artifacts](#artifacts)
+    * [Gradle setup (JVM)](#gradle-setup-jvm)
+    * [Multiplatform](#multiplatform)
+    * [Ktor dependencies](#ktor-dependencies)
 * [Quickstart](#quickstart)
-  * [Creating a Client](#creating-a-client)
-  * [Creating a Server](#creating-a-server)
+    * [Creating a Client](#creating-a-client)
+    * [Creating a Server](#creating-a-server)
 * [Core Concepts](#core-concepts)
-  * [MCP Primitives](#mcp-primitives)
-  * [Capabilities](#capabilities)
-    * [Server Capabilities](#server-capabilities)
-    * [Client Capabilities](#client-capabilities)
-  * [Server Features](#server-features)
-    * [Prompts](#prompts)
-    * [Resources](#resources)
-    * [Tools](#tools)
-    * [Completion](#completion)
-    * [Logging](#logging)
-    * [Pagination](#pagination)
-  * [Client Features](#client-features)
-    * [Roots](#roots)
-    * [Sampling](#sampling)
+    * [MCP Primitives](#mcp-primitives)
+    * [Capabilities](#capabilities)
+        * [Server Capabilities](#server-capabilities)
+        * [Client Capabilities](#client-capabilities)
+    * [Server Features](#server-features)
+        * [Prompts](#prompts)
+        * [Resources](#resources)
+        * [Tools](#tools)
+        * [Completion](#completion)
+        * [Logging](#logging)
+        * [Pagination](#pagination)
+    * [Client Features](#client-features)
+        * [Roots](#roots)
+        * [Sampling](#sampling)
 * [Transports](#transports)
-  * [STDIO Transport](#stdio-transport)
-  * [Streamable HTTP Transport](#streamable-http-transport)
-  * [SSE Transport](#sse-transport)
-  * [WebSocket Transport](#websocket-transport)
-  * [ChannelTransport (testing)](#channeltransport-testing)
+    * [STDIO Transport](#stdio-transport)
+    * [Streamable HTTP Transport](#streamable-http-transport)
+    * [SSE Transport](#sse-transport)
+    * [WebSocket Transport](#websocket-transport)
+    * [ChannelTransport (testing)](#channeltransport-testing)
 * [Connecting your server](#connecting-your-server)
 * [Examples](#examples)
 * [Documentation](#documentation)
@@ -183,17 +183,24 @@ fun main(args: Array<String>) = runBlocking {
 
 ### Creating a Server
 
-Create an MCP server that exposes a simple tool and runs on an embedded Ktor server with SSE transport:
+Create an MCP server that exposes a simple tool and runs on an embedded Ktor server with Streamable HTTP transport.
+For a full working project with all required dependencies, see
+the [simple-streamable-server](samples/simple-streamable-server) sample.
 
 <!--- CLEAR -->
+
 ```kotlin
+import io.ktor.serialization.kotlinx.json.json
+import io.ktor.server.application.install
 import io.ktor.server.cio.CIO
 import io.ktor.server.engine.embeddedServer
+import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
 import io.modelcontextprotocol.kotlin.sdk.server.Server
 import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
-import io.modelcontextprotocol.kotlin.sdk.server.mcp
+import io.modelcontextprotocol.kotlin.sdk.server.mcpStreamableHttp
 import io.modelcontextprotocol.kotlin.sdk.types.CallToolResult
 import io.modelcontextprotocol.kotlin.sdk.types.Implementation
+import io.modelcontextprotocol.kotlin.sdk.types.McpJson
 import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
 import io.modelcontextprotocol.kotlin.sdk.types.TextContent
 import io.modelcontextprotocol.kotlin.sdk.types.ToolSchema
@@ -228,7 +235,10 @@ fun main(args: Array<String>) {
     }
 
     embeddedServer(CIO, host = "127.0.0.1", port = port) {
-        mcp {
+        install(ContentNegotiation) {
+            json(McpJson)
+        }
+        mcpStreamableHttp {
             mcpServer
         }
     }.start(wait = true)
@@ -243,7 +253,7 @@ You can run the server and then connect to it using the client or test with the
 npx -y @modelcontextprotocol/inspector
 ```
 
-In the inspector UI, connect to `http://localhost:3000`.
+In the inspector UI, connect to `http://localhost:3000/mcp`.
 
 ## Core Concepts
 
@@ -787,13 +797,15 @@ private class MyServer :
 
 fun main() {
 -->
+
 ```kotlin
 embeddedServer(CIO, port = 3000) {
     mcpStreamableHttp(path = "/api/mcp") {
         MyServer()
     }
 }.start(wait = true)
 ```
+
 <!--- SUFFIX 
 }
 -->
@@ -831,6 +843,7 @@ private class MyServer :
 
 fun main() {
 -->
+
 ```kotlin
 embeddedServer(CIO, port = 3000) {
     install(SSE)
@@ -841,6 +854,7 @@ embeddedServer(CIO, port = 3000) {
     }
 }.start(wait = true)
 ```
+
 <!--- SUFFIX 
 }
 -->
@@ -880,12 +894,9 @@ allowing for easy testing of MCP functionality without the need for network setu
 
 ## Examples
 
-| Scenario                 | Description                                                     | Example                                                                  |
-|--------------------------|-----------------------------------------------------------------|--------------------------------------------------------------------------|
-| Streamable HTTP server   | Full MCP server with prompts, resources, tools, completions     | [samples/kotlin-mcp-server](./samples/kotlin-mcp-server)                 |
-| STDIO weather server     | Minimal STDIO transport server exposing weather info and alerts | [samples/weather-stdio-server](./samples/weather-stdio-server)           |
-| Interactive STDIO client | MCP client that connects over STDIO and pipes requests to LLMs  | [samples/kotlin-mcp-client](./samples/kotlin-mcp-client)                 |
-| Streamable HTTP client   | MCP client demo in a runnable notebook                          | [samples/notebooks/McpClient.ipynb](./samples/notebooks/McpClient.ipynb) |
+The [samples](./samples) directory contains runnable projects demonstrating
+MCP server and client implementations with various transports.
+See the [samples overview](./samples/README.md) for a comparison table and detailed descriptions.
 
 ## Documentation
 
@@ -899,4 +910,5 @@ Please see the [contribution guide](CONTRIBUTING.md) and the [Code of conduct](C
 
 ## License
 
-This project is licensed under Apache 2.0 for new contributions, with existing code under MIT—see the [LICENSE](LICENSE) file for details.
+This project is licensed under Apache 2.0 for new contributions, with existing code under MIT—see the [LICENSE](LICENSE)
+file for details.

docs/build.gradle.kts

@@ -6,6 +6,8 @@ plugins {
 dependencies {
     implementation(project(":kotlin-sdk"))
     implementation(libs.ktor.server.cio)
+    implementation(libs.ktor.serialization)
+    implementation(libs.ktor.server.content.negotiation)
 }
 
 tasks.matching {

samples/README.md

@@ -0,0 +1,55 @@
+# Kotlin MCP SDK Samples
+
+Runnable projects demonstrating MCP server and client implementations with the
+[Kotlin MCP SDK](https://github.com/modelcontextprotocol/kotlin-sdk).
+For background on the protocol itself, see the [MCP documentation](https://modelcontextprotocol.io/introduction).
+
+## Overview
+
+| Sample                                                 | Type              | Transport       | MCP Features                       |
+|--------------------------------------------------------|-------------------|-----------------|------------------------------------|
+| [simple-streamable-server](./simple-streamable-server) | Server            | Streamable HTTP | Tools, Resources, Prompts, Logging |
+| [kotlin-mcp-server](./kotlin-mcp-server)               | Server            | STDIO, SSE      | Tools, Resources, Prompts          |
+| [weather-stdio-server](./weather-stdio-server)         | Server            | STDIO           | Tools                              |
+| [kotlin-mcp-client](./kotlin-mcp-client)               | Client            | STDIO           | Tool discovery & invocation        |
+| [notebooks](./notebooks)                               | Client (Notebook) | Streamable HTTP | Tool discovery & invocation        |
+
+## Getting Started
+
+- **Building a server?** Start with [simple-streamable-server](./simple-streamable-server) — it
+  uses the recommended Streamable HTTP transport and covers tools, resources, prompts, and logging.
+- **Building a client?** Open the [notebooks](./notebooks) sample for a step-by-step walkthrough,
+  or see [kotlin-mcp-client](./kotlin-mcp-client) for a full CLI client with Anthropic API
+  integration.
+
+## Samples
+
+### Simple Streamable HTTP Server
+
+A minimal Streamable HTTP server with optional Bearer token authentication. Demonstrates tools
+(`greet`, `multi-greet`), a prompt template, a resource, and server-to-client logging notifications.
+[Read more →](./simple-streamable-server)
+
+### Kotlin MCP Server
+
+A multi-transport server supporting STDIO, SSE (plain), and SSE (Ktor plugin). Useful for exploring
+different transport modes side by side.
+[Read more →](./kotlin-mcp-server)
+
+### Weather STDIO Server
+
+A focused STDIO server that exposes weather forecast and alert tools backed by the weather.gov API.
+Includes Claude Desktop integration instructions.
+[Read more →](./weather-stdio-server)
+
+### Kotlin MCP Client
+
+An interactive CLI client that connects to any MCP server over STDIO and routes queries through
+Anthropic's Claude API, bridging MCP tools with LLM conversations.
+[Read more →](./kotlin-mcp-client)
+
+### MCP Client Notebook
+
+A Kotlin notebook that connects to a remote MCP server via Streamable HTTP and demonstrates ping,
+tool listing, and tool invocation — all in an interactive cell-by-cell format.
+[Read more →](./notebooks)

samples/kotlin-mcp-client/README.md

@@ -1,69 +1,50 @@
 # Kotlin MCP Client
 
-This project demonstrates how to build a Model Context Protocol (MCP) client in Kotlin that interacts with an MCP server
-via a STDIO transport layer while leveraging Anthropic's API for natural language processing. The client uses the MCP
-Kotlin SDK to communicate with an MCP server that exposes various tools, and it uses Anthropic's API to process user
-queries and integrate tool responses into the conversation.
-
-For more information about the MCP SDK and protocol, please refer to
-the [MCP documentation](https://modelcontextprotocol.io/introduction).
-
-## Prerequisites
-
-- **Java 17 or later**
-- **Gradle** (or the Gradle wrapper provided with the project)
-- An Anthropic API key set in your environment variable `ANTHROPIC_API_KEY`
-- Basic understanding of MCP concepts and Kotlin programming
+An interactive CLI client that connects to any MCP server over STDIO and pipes queries through
+Anthropic's Claude API.
 
 ## Overview
 
-The client application performs the following tasks:
+This sample demonstrates a complete MCP client workflow: launching an MCP server as a subprocess,
+discovering its tools, converting them to Anthropic's tool format, and running an interactive chat
+loop where Claude can call server tools on behalf of the user.
 
-- **Connecting to an MCP server** —
-  launches an MCP server process (implemented in JavaScript, Python, or Java) using STDIO transport.
-  It connects to the server, retrieves available tools, and converts them to Anthropic’s tool format.
-- **Processing queries** — 
-  accepts user queries, sends them to Anthropic’s API along with the registered tools, and handles responses.
-  If the response indicates a tool should be called, it invokes the corresponding MCP tool and continues the
-  conversation based on the tool’s result.
-- **Interactive chat loop** —
-  runs an interactive command-line loop, allowing users to continuously submit queries and receive responses.
+## Prerequisites
 
-## Building and Running
+- JDK 17+
+- An `ANTHROPIC_API_KEY` environment variable set with a valid Anthropic API key
+- An MCP server script to connect to (`.js`, `.py`, or `.jar`)
 
-Use the Gradle wrapper to build the application. In a terminal, run:
+## Build & Run
 
-```shell
-./gradlew clean build
-```
+Run the client, passing the path to an MCP server:
 
-To run the client, execute the jar file and provide the path to your MCP server script.
+```shell
+# Connect to a JVM server
+./gradlew run --args="path/to/server.jar"
 
-To run the client with any MCP server:
+# Connect to a Python server
+./gradlew run --args="path/to/server.py"
 
-```shell
-java -jar build/libs/<your-jar-name>.jar path/to/server.jar # jvm server
-java -jar build/libs/<your-jar-name>.jar path/to/server.py # python server
-java -jar build/libs/<your-jar-name>.jar path/to/build/index.js # node server
+# Connect to a Node.js server
+./gradlew run --args="path/to/build/index.js"
 ```
 
 > [!NOTE]
-> The client uses STDIO transport, so it launches the MCP server as a separate process.
+> The client uses STDIO transport, so it launches the MCP server as a subprocess.
 > Ensure the server script is executable and is a valid `.js`, `.py`, or `.jar` file.
 
-## Configuration for Anthropic
+## MCP Capabilities
 
-Ensure your Anthropic API key is available in your environment:
-
-```shell
-export ANTHROPIC_API_KEY=your_anthropic_api_key_here
-```
+From the **client** perspective, this sample demonstrates:
 
-The client uses `AnthropicOkHttpClient.fromEnv()` to automatically load the API key from `ANTHROPIC_API_KEY` and
-`ANTHROPIC_AUTH_TOKEN` environment variables.
+- **Tool discovery** — lists tools from the connected server and converts them to Anthropic's tool
+  format.
+- **Tool invocation** — when Claude's response requests a tool call, the client invokes the
+  corresponding MCP tool and feeds the result back into the conversation.
 
 ## Additional Resources
 
-- [MCP Specification](https://spec.modelcontextprotocol.io/)
+- [MCP Specification](https://modelcontextprotocol.io/specification/latest)
 - [Kotlin MCP SDK](https://github.com/modelcontextprotocol/kotlin-sdk)
-- [Anthropic Java SDK](https://github.com/anthropics/anthropic-sdk-java/tree/main)
+- [Anthropic Java SDK](https://github.com/anthropics/anthropic-sdk-java)