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.

How it all connects

Spring AI Playground is one local app that plays three roles at once - an MCP server that publishes tools to your agents, an MCP client that reaches out to external services, and a workbench where you build and vet those tools. You drive it through the Vaadin Flow UI (desktop app or browser); your AI clients - Claude Desktop and Code, Cursor, Codex, opencode, or any other MCP host - connect to the same built-in server over /mcp.

That server presents tools from three sources as one clean surface: a built-in library, tools you write in Tool Studio (each earns a Local Pass before it goes live), and external MCP servers you proxy and compose onto it - any vendor, any language. However a tool arrives, it is vetted before an agent can call it (see AI Agent Tool Safety): locally-run tools (built-in and authored) execute in a defense-in-depth sandbox with a visible Risk Level (L0-L5), human-in-the-loop approval, and an integrity check, while proxied and composed tools are risk-scored, HITL-gated, integrity-checked, and scanned for description poisoning.

Everything that runs - every chat, tool call, vector query, and MCP invocation - is captured in the built-in Observability dashboards. And it all runs local-first: Ollama by default, with OpenAI and OpenAI-compatible runtimes (llama.cpp, LM Studio, vLLM) optional, and chat grounded on your own documents through the local vector store.

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 - fourteen panels (Overview, Tokens & Cost, AI Models, Tool Studio, MCP Servers, MCP Inspector, Vector Database, Agentic Chat, Safety, Host, Ollama, 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 88 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) - with a parallel risk score scoring every external MCP server you connect (and a description poisoning scan on tools you re-expose) - see AI Agent Tool Safety Architecture
• see every chat, tool call, vector query, and MCP invocation in the fourteen 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

Security scope. The in-process sandbox is defense-in-depth for the local build-and-vet loop. It is not adversarial-grade isolation and not a gateway. To run tool code you do not trust, nest it in container or microVM isolation. See Isolation tiers.

Spring AI Playground - Demo
Connect an MCP server · compose a safe proxy · human-in-the-loop approval · full observability

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
The configuration editor stacks every card on one scrollable screen - numbered top to bottom below

The markers run top to bottom, and each card has a detailed step in the Desktop App configuration walkthrough:

1. Current Config and Setup Notes - explains the selected setting before you edit it (details)
2. Spring AI Playground Config - pick the provider type, choose a saved setting, and edit the override YAML (details)
3. Ollama Startup - Ollama endpoint, install / connection status, and the configured models (details)
4. Local Speech-to-Text - opt in to on-device voice input and download a Whisper model (details)
5. Default MCP Tools - choose which preset of built-in tools the MCP server exposes at boot (details)
6. Environment Variables - API keys and tool secrets, encrypted by your OS keychain (details)
7. JVM Settings - optional launch-time JVM options and application args (details)
8. Save and Launch action bar - Export, Import, Factory Reset, Save, and Save and Launch (details)

Ollama Model Manager
Review recommended models, search exact Ollama names on ollama.com, and manage downloaded models

The model manager opens from the Ollama Startup card; see Download and Manage Ollama Models for the full walkthrough, including how to copy an exact model name from ollama.com.

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 88 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 L3

searchWikipedia L3

extractPageContent L3

getCurrentTime L0

hash (SHA-256) L0

writeTextFile L4

→ Browse all 88 default tools across Examples (9) · Utilities (26) · Filesystem (11) · Global (21) · Korea (21).

External MCP - one click in the sidebar, fill ${ENV_VAR}, done

Gmail 🔐

Slack 🔐

GitHub 🔐

Notion 🔐

BigQuery 🔐

Stripe L2 🔐

→ 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, read a live risk score (L0-L5) before connecting, and proxy their tools onto the built-in server - compose multiple servers into one surface - each gated by per-tool human-in-the-loop.
• Default MCP Servers: 57 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 - with a Prompt Library of ready-to-use presets and {{variable}} templates, per-turn reasoning effort, review-then-act action cards (email, calendar, map) and clickable file paths, and rich code/math/diagram rendering.
• Observability: fourteen in-app dashboards covering token economics, tool and MCP behaviour, RAG quality, host runtime, and a live trace tail.

Why This Project Exists

As AI agents start calling real tools, what matters is no longer just the model's answer - it is which tool runs, what it can reach, whether it was tested, and whether you can see what it did afterward. Spring AI Playground started as a place to explore Spring AI's features; as agents and MCP became central to how AI apps are built, it grew into a tool-first environment for building, testing, validating, and operationalizing MCP tools - a safe local execution layer for the tools agents call.

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

Further Reading

• Getting Started: install the desktop app, configure models, and understand alternative runtimes
• Application Architecture: runtime layers, data flows, and extension points
• AI Agent Tool Safety Architecture: defense-in-depth sandbox model, policy resolution, threat model, and Risk Level reference
• AI Agent Observability Architecture: trace pipeline, storage tiers, configuration, and external export paths behind the fourteen dashboards
• Context Engineering Architecture: how each chat turn's context window is assembled from system prompt, retrieved documents, tools, memory, and per-request options
• Features: the main product areas and what they do
• Tutorials: follow end-to-end workflows for tools, MCP, vector search, and agentic chat

Analytics

This site uses Google Analytics to collect anonymous usage data - page views, interaction events, and device/browser metadata - for product analysis.

To opt out, use your browser's tracker-blocking extension or Do Not Track setting.

Was this page helpful? Ask on Discussions · Report a docs issue