Overview
What is FastMCP-Scala?
FastMCP-Scala is a Scala 3 library for building Model Context Protocol (MCP) servers. It provides annotation-driven and typed-contract APIs that run on both the JVM and Scala.js/Bun, targeting developers who want a low-ceremony way to expose tools, resources, and prompts to LLM clients via the MCP protocol.
How to use FastMCP-Scala?
Add the library dependency for JVM (%%) or Scala.js (%%%), then extend McpServerApp[Stdio, Self.type] or McpServerApp[Http, Self.type] and declare tools with @Tool annotations. The trait handles annotation scanning, schema derivation, and transport lifecycle automatically. For typed contracts, override tools, prompts, staticResources, or templateResources with McpTool, McpPrompt, etc.
Key features of FastMCP-Scala
- Annotation-driven tools, resources, and prompts with zero boilerplate
- Typed contracts as first-class, testable, cross-platform values
- Cross-platform support: JVM (JDK 17+) and Scala.js/Bun (Node 18+)
- Built on ZIO 2, Tapir, Jackson 3 (JVM), and zio-json (JS)
- Transport selected at compile time via a phantom type parameter
- Full MCP spec coverage including Streamable HTTP and experimental Tasks
Use cases of FastMCP-Scala
- Building single-file MCP servers for quick prototypes and demos
- Creating libraries of reusable, composable MCP tools and prompts
- Running production MCP servers with HTTP transport and session management
- Integrating long-running operations via the experimental Tasks API
FAQ from FastMCP-Scala
How do annotation-driven and typed-contract registration differ?
Annotations (@Tool + scanAnnotations) require no extra wiring and are best for quick servers, while typed contracts (McpTool, McpPrompt, etc.) are first-class values that support testing, composition, and cross-module sharing. Both can coexist on the same server.
What runtime dependencies are required?
JVM requires JDK 17+ and the Java MCP SDK 1.1.1. Scala.js requires Scala.js 1.x and runs on Bun (first-class) or Node 18+, using the TypeScript MCP SDK 1.29.0.
Is Tasks support production ready?
Tasks are experimental and off by default. They are enabled per server via McpServerSettings(tasks = TaskSettings(enabled = true)) and opt-in per tool. On JVM, Tasks only work with the built-in HTTP transport (stateless = false); stdio and stateless HTTP fail-fast if Tasks are enabled.
What transport options are available?
Transport is a compile-time phantom type: Stdio (for Claude Desktop, MCP Inspector) or Http (for remote clients, load balancers). The HTTP mode serves the full Streamable HTTP spec with optional stateless mode, and runs on a configurable port (default 8000).
