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 minimal boilerplate and cross‑platform compatibility.
How to use FastMCP-Scala?
Add the library dependency to your sbt build (com.tjclp module). Extend McpServerApp[Transport, Self.type] and declare tools using @Tool annotations or typed McpTool values. Transport is a phantom type parameter (Stdio or Http) that selects the runtime at compile time. Run the server with scala-cli or your preferred launcher.
Key features of FastMCP-Scala
- Annotation‑driven tools, resources, and prompts via
@Tool,@Resource,@Prompt - Typed contract values (
McpTool,McpPrompt,McpStaticResource,McpTemplateResource) - Built on ZIO 2 with Tapir‑derived schemas
- Uses Jackson 3 (JVM) / zio‑json (JS) for JSON handling
- Wraps official Java MCP SDK 1.1.1 and TS MCP SDK 1.29.0
- Compile‑time transport selection: stdio or HTTP (streamable or stateless)
- Experimental task support for long‑running operations
Use cases of FastMCP-Scala
- Rapid prototyping of MCP servers with minimal ceremony
- Production servers with testable, composable contract definitions
- Cross‑platform MCP servers that run on both JVM and JavaScript runtimes
- Exposing tools, resources, and prompts to MCP clients (e.g., Claude Desktop, MCP Inspector)
- Integrating MCP with effect systems like ZIO, Cats Effect, or plain values
FAQ from FastMCP-Scala
What platforms does FastMCP-Scala support?
It supports the JVM (JDK 17+) and Scala.js 1.x (runs on Bun first‑class and Node 18+).
How do I choose between annotations and typed contracts?
Annotations (@Tool + scanAnnotations) are best for quick servers and prototypes; typed contracts (McpTool, etc.) suit libraries, cross‑module sharing, and production codebases. Both can coexist on the same server.
What transports are available?
Stdio (for Claude Desktop, MCP Inspector) and HTTP (for remote clients, load balancers). HTTP supports streamable mode with SSE or stateless request/response mode.
How are schemas derived?
Tool and resource schemas are derived from method signatures and @Param annotations using Tapir. You can override any parameter’s schema with a raw JSON Schema fragment via @Param(schema = ...).
Can I access client context in a tool?
Yes, add an optional ctx: McpContext parameter to annotated methods or use McpTool.contextual in the typed‑contract path to read the client’s declared info and capabilities.
