spring-ai-playground

[!NOTE] Official repository

The official Spring AI Playground repository has moved to: https://github.com/spring-ai-community/spring-ai-playground

This repository is kept for personal experiments / notes and may diverge from the official version. For issues and pull requests, please use the official repository.

Spring AI Playground

Safe Local Execution Layer for AI Agent Tools

Spring AI Playground is a cross-platform desktop app for building, testing, validating, and executing MCP tools in a controlled local environment. It helps you create reusable MCP tools once and use them across macOS, Windows, and Linux through a self-contained runtime. Unlike platforms that focus primarily on generating agents or authoring tools, Spring AI Playground focuses on making the tools it manages inside the app safer and easier to inspect before reuse.

No pass, no run.

Every tool you build earns a Local Pass — a local test-run with your sample arguments. Only passing tools are added live to the built-in MCP server and become callable from Agentic Chat. A tool that has not passed is never exposed to an agent.

In Tool Studio, new or updated built-in tools are test-run before they are published to the built-in MCP server. You do not need to know Java, Spring, or JVM internals to use it. If you can install a desktop app and write a small JavaScript function, you can build tools here and connect them to hosts and clients such as Claude Desktop, Claude Code, Cursor, IDEs, and other MCP-compatible environments.

The Problem

AI agents can generate tools quickly, but generated tools are not inherently safe to execute.

Most platforms focus on creation.

Very few make verification part of the default workflow for built-in tool publication.

Who is this for?

Quick Start

The fastest path is the desktop app distributed through GitHub Releases.

Spring AI Playground is a standalone desktop app, so you can install it and start building MCP tools without setting up a Java project, Docker environment, or source build first.

1. Download the Desktop App

Choose the installer for your platform from the latest release:

Windows macOS Apple Silicon macOS Intel Linux DEB Linux RPM

Each badge resolves to the latest published release automatically and opens a confirm dialog with the filename, size, and OS-specific default save path. The downloaded file keeps the version in its name (e.g. spring-ai-playground-0.2.0-M4-mac-arm64.dmg). Or browse all available assets on the Releases page.

2. Install and Launch

Install the app like a normal desktop application, then launch Spring AI Playground from your applications menu.

The desktop app bundles the backend runtime together with a launcher that provides provider starter templates, YAML override editing, environment-variable based secret handling, and one-click launch.

If you install the app, you can run Spring AI Playground immediately without setting up Docker or running the source manually.

macOS

Gatekeeper may block the install flow in two places:

If the app still doesn’t open because it remains quarantined, and you trust the app, one practical workaround is:

xattr -dr com.apple.quarantine "/Applications/Spring AI Playground.app"

Windows

The most common warning appears when you run the downloaded installer (.exe).

If Microsoft Defender SmartScreen shows a warning such as “Windows protected your PC” or says the app is unrecognized:

Linux

Separate Gatekeeper- or SmartScreen-style reputation warnings are uncommon. When installing the .deb or .rpm package, you usually only need to complete the normal package-install confirmation steps.

For more detailed platform guidance, see the Getting Started guide.

Verify Your Download

Each release ships with two integrity guarantees. You do not have to verify, but it is recommended for production use.

1. SHA-256 checksum — every installer has a matching .sha256 file in the release assets.

# macOS / Linux
shasum -a 256 -c spring-ai-playground-0.2.0-M4-mac-arm64.dmg.sha256

# Windows (PowerShell)
Get-FileHash spring-ai-playground-0.2.0-M4-win-x64.exe -Algorithm SHA256
# compare the value with the one inside the .sha256 file

2. Sigstore build provenance (SLSA) — every installer is signed by the official GitHub Actions release workflow using a short-lived Sigstore key, and the attestation is recorded in the public transparency log.

gh attestation verify spring-ai-playground-0.2.0-M4-mac-arm64.dmg \
  --owner spring-ai-community

A successful verification proves the file came from this repo’s release workflow and was not tampered with after build.

First-Launch Configuration Screen
Desktop launcher overview with the built-in config editor

Spring AI Playground first-launch configuration screen

Ollama Model Manager
Review recommended models, search exact Ollama names, and manage downloaded models

Spring AI Playground Ollama model manager

Documentation

Detailed installation, configuration, features, and tutorials live in the documentation site:

Alternative runtimes are still supported. The same Spring Boot fat JAR drives every channel; switching to a stdio MCP transport is opt-in via the mcp-stdio Spring profile.

For the app/web experience (default — streamable-http MCP server on port 8282, Vaadin UI front and center):

For the stdio MCP server (drop-in for Claude Desktop, Claude Code, IDEs, and any other MCP-compatible client) — set SPRING_PROFILES_INCLUDE=mcp-stdio to layer the stdio transport on top of the default profile (so model config like Ollama / OpenAI is preserved):

Full setup details for both modes live in Getting Started: Alternative Runtimes.

Agentic Chat Demo
Tool-enabled agentic AI built with Spring AI and MCP

Spring AI Playground Agentic Chat Demo

Why Spring AI Playground?

The intended workflow is practical and composable:

Why Not Just Use Agent Builders?

Agent builders focus on generating tools and composing workflows.

Spring AI Playground focuses on validating tools and controlling execution.

It complements agent builders by providing a reliable execution layer.

Project Scope & Positioning

Spring AI Playground is a tool-first environment for building, testing, validating, and operationalizing MCP tools in a practical workflow.

It is best understood as a safe local execution layer for AI agent tools.

Note: This project is intentionally focused in its current stage.
The goal is to make MCP tool building, validation, inspection, and runtime exposure simple and reliable, so the tools you create here can be reused from MCP-compatible hosts and clients such as Claude Code, Claude Desktop, IDEs, and other agent environments.

Current focus:

It is not trying to replace the tools where agents actually run. It is designed to give you a clearer path from local tool prototype to inspectable, reusable MCP server.

Contributing & Scope

Please read this section before opening issues or submitting contributions.

Current Scope

Out of Scope For Now

Reporting Issues

Pick the right channel:

We triage issues regularly, and issues outside the current scope may be closed with guidance.

If you have a contribution that fits the current scope (bug report, doc fix, usage example), submit a PR or a targeted issue. For anything else, please open a Discussion first — but be aware we may not act on it given current capacity.

Anonymous Usage Telemetry

The official build sends anonymous usage data (page views, app surface, device/browser info) to the maintainer’s Google Tag Manager / Google Analytics account so the most-used features can be prioritized. IPs are anonymized by Google. The same opt-out switch applies to both the web app and every desktop launcher window (splash, server-splash, config editor, Ollama manager):

If you self-host this project for EU users, adding cookie consent on top is the operator’s responsibility under GDPR.

Upcoming Improvements

These are the near-term areas we plan to improve while keeping the project focused on practical, reusable tool execution.

Observability

Hardening Existing Capabilities

Platform Support

This site is open source. Improve this page.