// Scala.js — TS SDK-backed runtime on Bun/Node + the same annotation and typed-contract APIs.
libraryDependencies += "com.tjclp" %%% "fast-mcp-scala" % "0.4.0"

Built against Scala 3.8.3. JVM requires JDK 17+. Scala.js artifact is published for sjs1_3 (Scala.js 1.x); runs on Bun (first-class) and Node 18+.

Quickstart
A single-file server with one tool — the same code lives in HelloWorld.scala:

Choosing a registration path

| | Annotations (@Tool + scanAnnotations) | Typed contracts (McpTool) |

|---|---|---|

| Platform | JVM + Scala.js/Bun | JVM + Scala.js/Bun |

| Style | Methods on an object, discovered by macro | First-class vals |

| Schema | Derived from method signature & @Param | Derived from case-class fields & @Param |

| Testing | Call the method directly | Invoke .handler on the value |

| Composability | Whatever methods the object exposes | Collect into lists, generate from config |

| Best for | Quick servers, prototypes, single-module apps | Libraries, cross-module sharing, production codebases |

Both coexist on the same server — override tools / prompts / staticResources / templateResources on your McpServerApp to mount typed contracts alongside annotated methods:

override val tools = List(
McpToolAddArgs, AddResult { args =>
AddResult(args.a + args.b) // plain value — auto-lifted
}
)

Handler lambdas return plain values, ZIO, Either[Throwable, _], or scala.util.Try — the ToHandlerEffect[F[_]] typeclass picks the right lift. Bring your own given for other effect systems (cats.effect.IO, Monix, ...).

See AnnotatedServer.scala for the annotation path and ContractServer.scala for typed contracts.

Tools and @Param metadata

Every tool parameter can carry metadata that flows into the derived JSON schema:

- description — populates the schema's description field

- examples — populates the JSON Schema examples array (clients can show suggestions)

- required = false — combined with Option[...] or a default value, marks the field optional

- schema — raw JSON Schema fragment that overrides the derived schema entirely (useful for enum constraints, patterns, or numeric bounds Scala types can't express)

Full demo in AnnotatedServer.scala.

Tool hints
MCP Tool Annotations (a.k.a. behavioral hints) tell the client how your tool behaves. Set them on @Tool:

| Hint | Meaning |

|---|---|

| title | Human-readable display name (distinct from the wire-level name) |

| readOnlyHint | The tool only reads state; safe to call without confirmation |

| destructiveHint | The tool may irreversibly modify state — clients should confirm |

| idempotentHint | Repeated calls with the same args produce the same effect as one call |

| openWorldHint | The tool reaches outside the local process (network, filesystem, APIs) |

| returnDirect | Return the result directly to the user, skipping LLM post-processing |

See TaskManagerServer.scala for hints across a realistic tool set.

Resources (static and templated)
Static resources have a fixed URI and no parameters:

Templated resources use {placeholders} in the URI, matched against method parameter names:

Prompts

Return a List[Message] — fast-mcp-scala handles the MCP framing:

A prompt that returns a single String is automatically wrapped into a User message.

Context (McpContext)

Add an optional ctx: McpContext (annotation path) or use McpTool.contextual (typed-contract path) to access the client's declared info and capabilities:

Runnable demo: ContextEchoServer.scala.

Transports
Transport is a phantom type parameter on McpServerApp[T, Self] — Stdio or Http. The matching TransportRunner[T] given resolves at compile time, so there's no run-time transport plumbing in user code.

stdio (for Claude Desktop, MCP Inspector)

HTTP (for remote clients, load balancers, test harnesses)

Flip to Http and override settings to tune the listener. runHttp() serves the full MCP Streamable HTTP spec: POST /mcp for JSON-RPC, the mcp-session-id header for session tracking, and SSE streams for long-running calls.

@Tool(...) def hello(name: String): String = s"Hello, $name!"

Toggle stateless = true on McpServerSettings for request/response-only mode (no sessions, no SSE), useful behind load balancers.

Need lower-level control? Skip the sugar trait and construct directly — val server = McpServer("name", "0.1.0") returns the platform-appropriate server, and you can call .tool(...) / .runHttp() yourself inside your own ZIOAppDefault.

| Setting | Default | Description |

|---|---|---|

| host | 0.0.0.0 | Bind address |

| port | 8000 | Listen port |

| httpEndpoint | /mcp | JSON-RPC endpoint path |

| stateless | false | Disable sessions and SSE |

Curl recipes for both modes are in HttpServer.scala.

Tasks (experimental, off by default)
MCP Tasks (spec 2025-11-25) wrap long-running tools/call invocations in a durable, polled state machine. Clients send params.task: {ttl}, get a CreateTaskResult immediately, and then poll tasks/get / tasks/list / tasks/cancel / tasks/result until completion. Useful for LLM batch jobs, expensive computation, and integrations with external job APIs that would otherwise time out under request/response.

Enable per server (off by default — the spec marks Tasks experimental):

Opt in per tool — annotation path:

Opt in per tool — typed-contract path:

taskSupport values: "forbidden" (default), "optional" (clients may augment), "required" (clients must — bare calls return -32601).

Transport limitations: Tasks are dispatched inside fast-mcp-scala's own ZIO HTTP transport because the upstream Java MCP SDK 1.1.1 doesn't yet implement them. As a result:
- JVM: works on runHttp() with stateless = false (the default streamable transport). runStdio() and stateless HTTP fail-fast at startup if tasks.enabled is true.

- JS / Bun: works on both stateful and stateless runHttp(). runStdio() fails fast.

When enabled, the tasks capability is advertised at initialize and each opt-in tool surfaces execution.taskSupport on tools/list.

Customizing decoding (Jackson 3)
fast-mcp-scala uses Jackson 3 to turn raw JSON-RPC arguments into Scala values. Primitives, Scala enums, case classes, Option, List, Map, and java.time types work out of the box — no configuration required.

For custom wire formats, supply a given JacksonConverter[T]:

given JacksonConverter[LocalDateTime] = JacksonConverter.fromPartialFunction[LocalDateTime] {
case s: String => LocalDateTime.parse(s)
}

given JacksonConverter[Task] = DeriveJacksonConverter.derived[Task]

The handler receives a JacksonConversionContext (not a raw Jackson mapper) — see docs/jackson-converter-enhancements.md for the detailed API.

Two backends, one API
fast-mcp-scala is a single library with two real runtime backends — JVM and Scala.js/Bun — behind the same shared abstract API:

McpServerApp[T, Self] is the declarative entry point on both targets; the concrete backend resolves via the McpServerCoreFactory given (FastMcpServer on JVM, JsMcpServer on JS). Typed contracts (McpTool, McpPrompt, McpStaticResource, McpTemplateResource) compile and mount unchanged on both.

What the Scala.js backend gives you:
- A real MCP server runtime on Bun, wrapping the official @modelcontextprotocol/sdk — stdio (runStdio) and Streamable HTTP (runHttp) transports, with stateful (session + SSE) and stateless (JSON-response-only) modes.

- AJV-based schema validation of tool arguments, matching the JVM server's behaviour.

- JsMcpContext extension methods (getClientInfo, getClientCapabilities, getSessionId) for handlers that need client-session details.

Current platform parity:
| Capability | JVM | Scala.js (Bun-first) |

|---|---|---|

| McpServerApp[T, Self] sugar trait | ✅ | ✅ |

| @Tool / @Resource / @Prompt + scanAnnotations[T] | ✅ | ✅ |

| Typed contracts (McpTool, McpPrompt, McpStaticResource, McpTemplateResource) | ✅ | ✅ |

| ToolSchemaProvider[A] auto-derivation from @Param | ✅ via Tapir | ✅ via Tapir |

| ToHandlerEffect[F] — plain values / ZIO / Either / Try | ✅ | ✅ |

| Stdio transport | ✅ (Java SDK) | ✅ (TS SDK) |

| Streamable HTTP — stateful (sessions + SSE) | ✅ (ZIO HTTP) | ✅ (Bun.serve + Web-Standard transport) |

| Streamable HTTP — stateless | ✅ | ✅ |

| Custom decoders | ✅ JacksonConverter | ✅ given JsonDecoder[T] → McpDecoder[T] via zio-json |

Node / Deno parity for the HTTP listener is a follow-up; the same WebStandardStreamableHTTPServerTransport works across runtimes, only the Bun.serve(...) entry point is Bun-specific today.

Proof: the conformance suite at JsServerConformanceTest.scala stands up a JsMcpServer in-process and drives every MCP operation through the official TS SDK client via InMemoryTransport; JsServerHttpTest.scala verifies the Bun HTTP routing; ConformanceTest.scala runs a JS client against the JVM server for cross-backend parity.

Running on Bun