FastMCP-Scala

@arcaputo3

About FastMCP-Scala

A quick and easy way to deploy MCP servers using Scala

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "fast-mcp-scala": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/inspector",
        "scala-cli",
        "scripts/quickstart.sc"
      ]
    }
  }
}

Tools

No tools detected

Fetch the live tool list by running this server in a temporary sandbox using the button above.

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

Frequently asked questions

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