FastMCP-Scala

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).