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.

No pass, no run.

Every tool you build earns a Local Pass — a local test-run with sample arguments. Only tools that pass are added live to the built-in MCP server and become callable from Agentic Chat. Nothing you author reaches an agent until you have seen it work on your own machine.

Safe execution does not end at publication. Every chat, tool call, vector lookup, and MCP invocation that runs in the app lands in the built-in Observability dashboards — twelve panels (Overview, Tokens & Cost, AI Models, Tool Studio, MCP Servers, MCP Inspector, Vector Database, Agentic Chat, Host, Web Application, Logs, Traces) backed by a ring buffer with dated disk persistence. Drill from any row into the trace timeline and raw spans, jump to the conversation thread, and deep-link back into Agentic Chat — the tools you let an agent call are also the tools you can audit in detail afterwards.

The desktop app is the recommended default experience, but Docker and local source execution are still supported when you want a server-style deployment or a development workflow.

Unlike many playgrounds that stop at prompt testing, this project connects AI conversations to real actions while making the tools it manages inside the app safer and easier to inspect before reuse:

build JavaScript tools directly in the app
earn a Local Pass by test-running each tool against sample arguments you define
add tools live to the built-in MCP server the moment each passes — no restart, no redeploy
start immediately with 86 pre-loaded default tools spanning web fetch / datetime / math / security / encoding / crypto / filesystem / GitHub / Wikipedia / weather / finance / geo / Korean services — see the spotlight section below for the categorised browse
connect external surfaces in one click with 57 preset MCP server connections (Gmail · Outlook · Notion · Slack · GitHub · Linear · Atlassian · Stripe · Figma · BigQuery · Cloudflare · Tavily · MCP Everything · …) — same spotlight section below covers the full per-category browse
validate retrieval pipelines against your own documents
run agentic chat that combines tool use and grounded context (e.g. "Get today's weather and send it to Slack")
run every tool through a defense-in-depth GraalVM sandbox with a deny-first class allowlist, SSRF-guarded fetch, rooted safety.fs, statement + wall-clock limits, and a visible per-tool Risk Level (L0–L5) — see AI Agent Tool Safety Architecture
see every chat, tool call, vector query, and MCP invocation in the twelve built-in Observability dashboards — drill into span timelines, jump back to the source conversation, watch token cost and latency live, deep-link from a trace into Agentic Chat

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

Quick Start¶

The recommended default is the desktop app distributed from 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¶

Pick the installer for your platform. Each link resolves to the latest published release automatically.

Or browse all available assets on the Releases page. Need verification info?

2. Install and Launch¶

Install the package the same way you would for 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 server manually.

macOS

Gatekeeper may block the install flow in two places:

When you open the downloaded DMG, macOS may show a warning such as “cannot be opened because the developer cannot be verified.” If you trust the release source, go to System Settings > Privacy & Security and click Open Anyway.

After copying the app into Applications, macOS may block the first app launch again. If that happens, open the app once, then return to System Settings > Privacy & Security and click Open Anyway.

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:

Click More info

Then click Run anyway

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 and first-launch configuration screens, see Getting Started.

First-Launch Configuration Screen
Desktop launcher overview — config editor, Default MCP Tools curation, JVM & environment cards on one screen

Spring AI Playground first-launch configuration screen — Spring AI Playground Config + Ollama startup + Default MCP Tools + Environment Variables + JVM Settings

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

Spring AI Playground Ollama model manager

3. Start with the Built-in Desktop Runtime¶

The desktop build is intended to be the easiest way to get started without setting up Docker or running the server manually.

4. Optional: Use Docker Instead¶

By default the container behaves like the desktop / source app — Vaadin web UI on http://localhost:8282 and a streamable-http MCP server in the same process. To use it as a stdio MCP server for Claude Desktop and other MCP clients instead, add -e SPRING_PROFILES_INCLUDE=mcp-stdio (see the Docker section in Alternative Runtimes).

docker run -d -p 8282:8282 --name spring-ai-playground \
  -e SPRING_AI_OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -v spring-ai-playground:/root \
  --restart unless-stopped \
  ghcr.io/spring-ai-community/spring-ai-playground:latest

Then open http://localhost:8282.

What used to take an afternoon — already wired in¶

Installing an external MCP server normally means cloning a repo, installing the right runtime, registering an OAuth app, exporting tokens, and restarting your host. We did that 57 times so you don't have to. The 86 default tools ship in the same box. Every tool carries a visible Risk Level (L0–L5) — the sandbox, Local Pass, ${ENV_VAR} substitution, and SecretMasking handle the rest.

Built-in tools — call from chat the moment you launch¶

getWeather L0

searchWikipedia L0

extractPageContent L0

getCurrentTime L0

hash (SHA-256) L0

writeTextFile L4

→ Browse all 86 default tools across Examples (7) · Utilities (26) · Filesystem (10) · Global (22) · Korea (21).

External MCP — one click in the sidebar, fill `${ENV_VAR}`, done¶

Gmail 🔐

Slack 🔐

GitHub 🔐

Notion 🔐

BigQuery 🔐

Stripe L4 🔐

→ Browse all 57 preset MCP connections across Productivity & Communication (8) · Dev & Project Management (12) · Data & Cloud (17) · Business (12) · Search (6) · Examples (2). New to this surface? Walk through Tutorial 9 — MCP Everything: All 8 Primitives in One Walkthrough.

What You Can Do¶

AI Models: switch between Ollama, OpenAI, and OpenAI-compatible runtime paths.
Tool Studio: build low-code tools in JavaScript and expose them instantly through MCP.
MCP Server: inspect external MCP servers and consume built-in MCP tools.
Default MCP Catalog: 49 preset external MCP server connections (Gmail, Notion, Slack, GitHub, Tavily, ...) gated on ${ENV_VAR} placeholders.
RAG: upload content, chunk it, embed it, index it, and validate retrieval quality.
Agentic Chat: combine grounded context, built-in tools, and explicitly trusted MCP connections in one interaction flow.
Observability: twelve in-app dashboards covering token economics, tool and MCP behaviour, RAG quality, host runtime, and a live trace tail.

Why This Project Exists¶

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

Its current focus is:

providing a UI-driven environment for building, testing, and validating MCP tools in a practical workflow
making test-before-publish the default path for built-in local tool exposure
testing tool execution flows, environment-backed tool configuration, and RAG integration in one place
making tools easier to inspect, easier to test, and easier to operationalize before they are reused elsewhere
supporting practical single-agent workflows through Agentic Chat with tools and grounded context. See Agentic Chat Architecture Overview.
promoting validated built-in tools into reusable MCP-hosted runtimes that can be shared across multiple MCP-compatible hosts and clients

It is intentionally opinionated and scope-limited in its current stage. The goal is a stable, reproducible platform for practical MCP tool work rather than a feature-complete agent orchestration product.

Documentation Flow¶

Getting Started: install the desktop app first, configure models, and understand alternative runtimes
Architecture: runtime layers, data flows, and extension points (Application + AI Agent Tool Safety)
Features: the main product areas and what they do
Tutorials: follow real workflows for tools, MCP, vector search, and agentic chat