Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
db72eb4
feat(T8): expose request facts to handlers and gate logs by _meta log…
sideeffffect Nov 19, 2026
0756163
feat(T8): let plain tool, prompt and resource logic read the server c…
sideeffffect Nov 19, 2026
26b89ca
feat(T8): reject modern tool calls missing a required client capability
sideeffffect Nov 19, 2026
68199c5
fix(T8): accept JSON-RPC request ids beyond the Int range
sideeffffect Nov 19, 2026
33eb72a
feat(T8): add test_missing_capability and test_logging_tool conforman…
sideeffffect Nov 19, 2026
ebcdb7f
docs(T8): document request facts, per-request log level and -32021
sideeffffect Nov 19, 2026
178aef7
test(T8): expect no log notifications for modern requests without a l…
sideeffffect Nov 19, 2026
345050a
feat(T8): validate server/discover like other modern requests
sideeffffect Nov 19, 2026
ade71f1
feat(T16): add a notification publisher and subscriptions/listen hand…
sideeffffect Nov 19, 2026
9923d42
feat(T16): serve subscriptions/listen streams over streaming HTTP
sideeffffect Nov 19, 2026
d8d6f60
feat(T16): serve subscriptions/listen over stdio
sideeffffect Nov 19, 2026
4ec4556
feat(T16): add test_trigger_tool_change and test_trigger_prompt_chang…
sideeffffect Nov 19, 2026
51da456
docs(T16): document the notification publisher and subscriptions/listen
sideeffffect Nov 19, 2026
3c82336
fix(T14): send resultType input_required and allow a state-only Input…
sideeffffect Nov 19, 2026
161d019
feat(T14): let tools, prompts and resources end with an input-require…
sideeffffect Nov 19, 2026
673cb29
feat(T14): answer an early HTTP error of a streaming call as plain JSON
sideeffffect Nov 19, 2026
87f0c37
test(T14): cover input-required outcomes over stdio and sync HTTP
sideeffffect Nov 19, 2026
e0cfb44
feat(T14): add the input-required conformance fixtures
sideeffffect Nov 19, 2026
4ad3269
docs(T14): document asking the client for input
sideeffffect Nov 19, 2026
2480074
feat(T14): sign and verify the request state with an HMAC-SHA256 signer
sideeffffect Nov 19, 2026
57d3c2d
feat(T14): add the request-state conformance fixtures
sideeffffect Nov 19, 2026
5b0e8a7
docs(T14): document the request state signer
sideeffffect Nov 19, 2026
bf7ee20
feat(T13): mark tool input properties with x-mcp-header
sideeffffect Nov 19, 2026
ba531f5
feat(T13): validate Mcp-Param headers and Base64 sentinel values
sideeffffect Nov 19, 2026
177c384
test(T13): check request headers on the ZIO, Ox and Pekko HTTP servers
sideeffffect Nov 19, 2026
38197cb
feat(T13): offer an x-mcp-header tool on the conformance server
sideeffffect Nov 19, 2026
249020e
docs(T13): document x-mcp-header and the request header checks
sideeffffect Nov 19, 2026
0654f6b
fix(T16): deliver events published right after a subscription is ackn…
sideeffffect Nov 19, 2026
66a438c
Merge branch 'feat/t16-subscriptions-listen' into feat/t14-server-mrtr
sideeffffect Nov 19, 2026
f893d8c
Merge branch 'feat/t14-server-mrtr' into feat/t14-request-state
sideeffffect Nov 19, 2026
565cf13
Merge branch 'feat/t14-request-state' into feat/t13-mcp-header
sideeffffect Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 0 additions & 17 deletions conformance-baseline-2026-07-28.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,25 +12,8 @@ server:
- tasks-request-state-removal
- tasks-required-task-error
- tasks-wire-fields
# server-to-client input requests during tools/call — T5, https://github.com/softwaremill/chimp/issues/243
- input-required-result-basic-elicitation
- input-required-result-basic-list-roots
- input-required-result-basic-sampling
- input-required-result-capability-check
- input-required-result-multiple-input-requests
- input-required-result-multi-round
- input-required-result-non-tool-request
- input-required-result-request-state
- input-required-result-result-type
- input-required-result-tampered-state
# full stateless lifecycle (needs subscription serving)
- server-stateless
# x-mcp-header custom headers in the tool DSL — T13, https://github.com/softwaremill/chimp/issues/251
- http-custom-header-server-validation
# the harness records a failure in a non-primary run of these scenarios (the primary run passes)
- sep-2164-resource-not-found
- input-required-result-missing-input-response
- input-required-result-ignore-extra-params
client:
# OAuth client flows — chimp's client has no full OAuth support yet
- auth/authorization-server-migration
Expand Down
9 changes: 5 additions & 4 deletions core/src/main/scala/chimp/protocol/Ids.scala
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,16 @@ package chimp.protocol

import io.circe.{Codec, Decoder, Encoder, Json}

opaque type RequestId = String | Int
opaque type RequestId = String | Int | Long
object RequestId:
def apply(value: String | Int): RequestId = value
def unapply(id: RequestId): Option[String | Int] = Some(id)
def apply(value: String | Int | Long): RequestId = value
def unapply(id: RequestId): Option[String | Int | Long] = Some(id)
given encoder: Encoder[RequestId] = Encoder.instance:
case s: String => Json.fromString(s)
case i: Int => Json.fromInt(i)
case l: Long => Json.fromLong(l)
given decoder: Decoder[RequestId] = Decoder.instance: c =>
c.as[String].map(RequestId(_)).orElse(c.as[Int].map(RequestId(_)))
c.as[String].map(RequestId(_)).orElse(c.as[Int].map(RequestId(_))).orElse(c.as[Long].map(RequestId(_)))
given codec: Codec[RequestId] = Codec.from(decoder, encoder)

opaque type ProgressToken = String | Int
Expand Down
4 changes: 2 additions & 2 deletions core/src/main/scala/chimp/protocol/Mrtr.scala
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ object InputResponse:
* opaque `requestState` the client echoes back on its response, and the modern result envelope fields.
*/
final case class InputRequiredResult(
inputRequests: Map[String, InputRequest],
inputRequests: Option[Map[String, InputRequest]] = None,
requestState: Option[String] = None,
resultType: ResultType = ResultType.Incomplete,
resultType: ResultType = ResultType.InputRequired,
_meta: Option[Map[String, Json]] = None
) derives io.circe.Codec
21 changes: 15 additions & 6 deletions core/src/main/scala/chimp/protocol/Versioning.scala
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ object ProtocolMeta:
val ProtocolVersionKey: String = "io.modelcontextprotocol/protocolVersion"
val ClientInfo: String = "io.modelcontextprotocol/clientInfo"
val ClientCapabilities: String = "io.modelcontextprotocol/clientCapabilities"
val LogLevel: String = "io.modelcontextprotocol/logLevel"
val ServerInfo: String = "io.modelcontextprotocol/serverInfo"
val SubscriptionId: String = "io.modelcontextprotocol/subscriptionId"

Expand All @@ -29,19 +30,27 @@ object ProtocolMeta:
data = Some(Json.obj("requested" -> requested.asJson, "supported" -> supported.asJson))
)

/** The type of a modern (2026-07-28+) result: `complete` for a finished result, `incomplete` for one that needs another round trip (MRTR
* input-required).
/** A `MissingRequiredClientCapability` error (`-32021`) naming the capabilities the client must declare to make the request. */
def missingClientCapabilityError(required: ClientCapabilities): JSONRPCErrorObject =
JSONRPCErrorObject(
code = JSONRPCErrorCodes.MissingRequiredClientCapability.code,
message = "Missing required client capability",
data = Some(Json.obj("requiredCapabilities" -> required.asJson.deepDropNullValues))
)

/** The type of a modern (2026-07-28+) result: `complete` for a finished result, `input_required` for one that needs another round trip
* (MRTR).
*/
enum ResultType(val name: String):
case Complete extends ResultType("complete")
case Incomplete extends ResultType("incomplete")
case InputRequired extends ResultType("input_required")

object ResultType:
given Encoder[ResultType] = Encoder.instance(resultType => Json.fromString(resultType.name))
given Decoder[ResultType] = Decoder.decodeString.emap:
case "complete" => Right(Complete)
case "incomplete" => Right(Incomplete)
case other => Left(s"Unknown result type: $other")
case "complete" => Right(Complete)
case "input_required" => Right(InputRequired)
case other => Left(s"Unknown result type: $other")

/** Whether a cached response may be shared across authorization contexts (`Public`) or not (`Private`). */
enum CacheScope:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -90,8 +90,9 @@ class Schema20260728ConformanceSpec extends SchemaConformance:
)
validate(
"InputRequiredResult",
InputRequiredResult(inputRequests = Map("name" -> request), requestState = Some("state-1"))
InputRequiredResult(inputRequests = Some(Map("name" -> request)), requestState = Some("state-1"))
)
InputRequiredResult(requestState = Some("state-1")).asJson.hcursor.get[String]("resultType") shouldBe Right("input_required")

it should "produce CallToolRequestParams carrying inputResponses and requestState that match the spec schema" in:
validate(
Expand Down
1 change: 1 addition & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ and [sttp](https://github.com/softwaremill/sttp), supporting the variety of the
server/prompts
server/resources
server/capabilities
server/mrtr
server/examples

.. toctree::
Expand Down
104 changes: 99 additions & 5 deletions docs/server/capabilities.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Server capabilities

Most tools just answer a request, so `serverLogic`/`handle` expose no context. A tool that needs to **push to the client while it runs** uses `streamingServerLogic`, which receives a `StreamingServerContext[F]`:
Most tools just answer a request, so `serverLogic`/`handle` expose no context. Use `serverLogicWithContext` to read the facts of the request (see [request facts](#request-facts)). A tool that needs to **push to the client while it runs** uses `streamingServerLogic`, which receives a `StreamingServerContext[F]`:

- `reportProgress` — [progress](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress) notifications, auto-wired to the request's progress token.
- `log` — [logging](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging) notifications.
- `log` — [logging](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging) notifications. For a modern (`2026-07-28`) request, chimp sends a message only when its level is at or above the [per-request log level](https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/logging#per-request-log-level) in `_meta` (`io.modelcontextprotocol/logLevel`). If the request sets no level, chimp sends no messages. For a legacy request, chimp sends all messages; use `.withLoggingLevel` to receive `logging/setLevel`.

```{note}
Pushing to the client requires an open stream, so a `streamingServerLogic` tool is registered with `addStreamingTool` on a `StreamingMcpServer`, and will not compile on the plain request/response endpoint.
Expand All @@ -28,22 +28,116 @@ val work = tool("work")
val server = StreamingMcpServer[Identity]().addStreamingTool(work)
```

Server-wide capabilities are enabled by registering a handler — only what you wire up is advertised: `.withCompletion`, `.withLoggingLevel`, `.withSubscriptions`. `.withLoggingLevel` and `.withSubscriptions` serve only legacy clients: `2026-07-28` removed `logging/setLevel` and `resources/{,un}subscribe`, so a modern client gets a `404` for them (see below).
Server-wide capabilities are enabled by registering a handler — only what you wire up is advertised: `.withCompletion`, `.withLoggingLevel`, `.withSubscriptions`, `.withPublisher`. `.withLoggingLevel` and `.withSubscriptions` serve only legacy clients: `2026-07-28` removed `logging/setLevel` and `resources/{,un}subscribe`, so a modern client gets a `404` for them (see below). `.withPublisher` serves only modern clients (see [publishing list changes and resource updates](#publishing-list-changes-and-resource-updates)).

## Protocol versions

chimp is **dual-era**: it speaks the legacy handshake revisions (`2025-11-25` and earlier, negotiated via `initialize`) and the modern `2026-07-28` revision, where each request carries its protocol version in `_meta` under `io.modelcontextprotocol/protocolVersion` instead of a handshake.

The server answers `server/discover` automatically with its supported versions, capabilities and identity (`serverInfo` in `_meta`), so a client can learn them in one request without connecting. A request that declares a protocol version the server does not support is rejected with an `UnsupportedProtocolVersion` error (`-32022`) listing the supported versions, per the [versioning compatibility matrix](https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning#compatibility-matrix). No configuration is required for any of this.

A request is **modern** when its `_meta` or its `MCP-Protocol-Version` header declares `2026-07-28`. A legacy client that writes a legacy version into `_meta` stays on the legacy rules. chimp checks every modern request before any tool logic runs, and answers a failed check with a plain JSON error and its own HTTP status:
A request is **modern** when its `_meta` or its `MCP-Protocol-Version` header declares `2026-07-28`. A legacy client that writes a legacy version into `_meta` stays on the legacy rules. chimp checks every modern request, `server/discover` included, before any tool logic runs, and answers a failed check with a plain JSON error and its own HTTP status. A `server/discover` that declares no version (or a legacy version) gets no checks, so any client can discover the server:

| Problem | JSON-RPC error | HTTP status |
|---|---|---|
| unsupported protocol version | `-32022` UnsupportedProtocolVersion | `400` |
| `_meta` has no `protocolVersion` or no `clientCapabilities` | `-32602` InvalidParams | `400` |
| the `MCP-Protocol-Version` header and `_meta` declare different versions | `-32020` HeaderMismatch | `400` |
| the `MCP-Protocol-Version` header is missing (HTTP only), or it and `_meta` declare different versions | `-32020` HeaderMismatch | `400` |
| `Mcp-Method` / `Mcp-Name` header missing or different from the body (HTTP only) | `-32020` HeaderMismatch | `400` |
| `tools/call` with an `Mcp-Param-{name}` header missing, malformed or different from its argument (HTTP only) | `-32020` HeaderMismatch | `400` |
| removed method (`initialize`, `ping`, `logging/setLevel`, `resources/subscribe`, `resources/unsubscribe`) or unknown method | `-32601` MethodNotFound | `404` |
| `subscriptions/listen` on a server without a publisher, or on the sync HTTP transport | `-32601` MethodNotFound | `404` |
| `tools/call` of a tool whose required client capabilities `_meta` does not declare | `-32021` MissingRequiredClientCapability | `400` |

Over HTTP, a modern request must carry the SEP-2243 standard headers: `Mcp-Method` with the body's `method`, and `Mcp-Name` with `params.name` on `tools/call` and `prompts/get`, or `params.uri` on `resources/read`. Header names are case-insensitive, values are case-sensitive, and surrounding whitespace is ignored. chimp's own client sends these headers and the `_meta` when you give it a modern protocol version — see [client transport](../client/transport.md).

A modern `tools/call` over HTTP must also carry an `Mcp-Param-{name}` header for each argument that the tool marks with [`x-mcp-header`](tools.md#mirroring-arguments-into-http-headers). The server compares each header with its argument:

- An argument that is present needs its header. An argument that is `null` or absent needs no header, and a header for it is a mismatch.
- Integers are compared numerically, so `42.0` in the header equals `42` in the body. Booleans are `true` or `false`, and strings are compared literally.
- `Mcp-Param-*` headers that match no marked argument are ignored.

`Mcp-Name` and `Mcp-Param-*` values can use the Base64 sentinel form `=?base64?{value}?=`, which carries the UTF-8 bytes of the value. The server decodes a value in this form before the comparison. A sentinel with invalid Base64 (bad padding, characters outside the alphabet) or invalid UTF-8, and a value with characters that are not visible ASCII, space or tab, are a `-32020`. A value without the complete wrapper is compared literally.

Legacy requests and stdio get none of these header checks.

## Request facts

Each handler can read the facts of its request from `ctx.request`, a `RequestInfo`:

- `protocolVersion` — the protocol version of the request.
- `clientCapabilities` and `clientInfo` — what the client declares in `_meta`.
- `logLevel` — the per-request log level from `_meta`.
- `progressToken` — the progress token from `_meta`.
- `inputResponses` and `requestState` — on the retry of an input-required outcome, the answers of the client and the echoed state (see [asking the client for input](mrtr.md)).

A modern request carries all of these in `_meta`. The server keeps no state between requests, so a legacy request gives only the protocol version (from the `MCP-Protocol-Version` header or `_meta`) and the progress token. The other facts are `None`.

`serverLogicWithContext` gives the context to tools, prompts, resources and resource templates on every server. `streamingServerLogic` and `securedStreamingServerLogic` give it too, because `StreamingServerContext` is a `ServerContext`.

A tool that needs a client capability declares it with `withRequiredClientCapabilities`. If a modern request does not declare all of these capabilities in `_meta`, chimp rejects it before the logic runs, with `-32021` (MissingRequiredClientCapability), HTTP `400`, and the capabilities in `data.requiredCapabilities`. chimp compares the capabilities key by key, also in nested objects. A legacy request has no per-request capabilities, so chimp does not check it.

```scala mdoc:compile-only
import chimp.server.*
import chimp.protocol.ClientCapabilities
import io.circe.{Codec, Json}
import sttp.shared.Identity
import sttp.tapir.*

case class AskInput(question: String) derives Codec, Schema

val ask = tool("ask")
.withRequiredClientCapabilities(ClientCapabilities(sampling = Some(Json.obj())))
.input[AskInput]
.serverLogicWithContext[Identity]: (in, ctx, _) =>
val client = ctx.request.clientInfo.fold("unknown client")(_.name)
ToolResult.text(s"$client asked: ${in.question}")

val server = McpServer[Identity]().addTool(ask)
```

## Publishing list changes and resource updates

A server tells its clients that its tools, prompts or resources changed, or that a resource was updated, through a `NotificationPublisher`. Create one, give it to the server with `.withPublisher`, and call it from any part of your application, not only from a tool:

- `toolsListChanged()`, `promptsListChanged()`, `resourcesListChanged()` — send the list-changed notification of that list.
- `resourceUpdated(uri)` — send `notifications/resources/updated` for one resource URI.
- `close()` — end all open subscriptions, for example when the server shuts down.

The methods are thread-safe and return `Unit`, not an effect. In an effect system, wrap the call, for example `ZIO.succeed(publisher.toolsListChanged())`.

```scala mdoc:compile-only
import chimp.server.*
import chimp.server.ox.OxServerHttpTransport
import io.circe.Codec
import sttp.shared.Identity
import sttp.tapir.*

case class NoteInput(text: String) derives Codec, Schema

val publisher = NotificationPublisher()

val addNote = tool("add_note")
.input[NoteInput]
.handle: _ =>
publisher.resourcesListChanged()
ToolResult.text("note added")

val server = McpServer[Identity]().addTool(addNote).withPublisher(publisher).streaming
val endpoint = OxServerHttpTransport(List("mcp")).serve(server)
```

A `2026-07-28` client receives these notifications on a [`subscriptions/listen`](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/subscriptions) stream:

- With a publisher, `server/discover` advertises `listChanged` for tools, prompts and resources, and `subscribe` for resources. The capability of a list is there only when the server has that feature, for example `prompts` only when the server has prompts. The `initialize` result for legacy clients does not change: it advertises no list changes, and `subscribe` only for `.withSubscriptions`.
- The first message on the stream is `notifications/subscriptions/acknowledged`. Its filter is the part of the requested filter that the server honours. The server sends no other notification types.
- Each message on the stream carries the id of the listen request in `_meta`, under `io.modelcontextprotocol/subscriptionId`.
- `notifications/resources/updated` goes only to the streams which list the URI in `resourceSubscriptions`.
- Progress and log notifications do not go on a listen stream. They stay on the stream of their request.
- Over HTTP, a subscription ends when the client closes the stream. The server notices a closed stream at the latest when it next sends on it.
- Over stdio, all subscriptions share the one channel. The client ends one with `notifications/cancelled` that names the listen request. When the input ends, the server ends each open subscription.
- When the server ends a subscription (on `close()`, or at the end of the stdio input), it sends a successful `subscriptions/listen` result with the subscription id. Over stdio, it then sends `notifications/cancelled` for the listen request.

```{note}
A listen stream needs a streaming transport. On the sync HTTP transport (`McpServer.endpoint`), the server answers `subscriptions/listen` with `-32601` and advertises no list changes.
```
Loading
Loading