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 lands in fourteen built-in Observability dashboards, from token cost down to the trace timeline of a single call, so the tools you let an agent call are also the tools you can audit afterwards.
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.
ChatGPT works through the management tools and you approve each step; the rest of the series plays next
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 with a launcher for provider templates, YAML overrides, secrets and one-click launch, so there is no Docker or server to set up.
macOS, Windows or Linux blocks the installer?
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.
The 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:
- Current Config and Setup Notes - explains the selected setting before you edit it (details)
- Spring AI Playground Config - pick the provider type, choose a saved setting, and edit the override YAML (details)
- Ollama Startup - Ollama endpoint, install / connection status, and the configured models (details)
- Local Speech-to-Text - opt in to on-device voice input and download a Whisper model (details)
- Default MCP Tools - choose which preset of built-in tools the MCP server exposes at boot (details)
- Environment Variables - API keys and tool secrets, encrypted by your OS keychain (details)
- JVM Settings - optional launch-time JVM options and application args (details)
- Save and Launch action bar - Export, Import, Factory Reset, Save, and Save and Launch (details)
The 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.
Prefer Docker? Run the same app in a container
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.
Key Features¶
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:
-
connect your AI over MCP and let it do the work, inside one safety net - Claude, ChatGPT, Cursor or any MCP client connects to the playground's
/mcponce, reads the guides, start prompts and example tools the app serves, with this app's own sandbox limits filled in, and through thesaip_*management tools does the work itself:- writes, tests and publishes JavaScript tools that earn their Local Pass (Tutorial 18)
- registers external MCP servers and proxies their tools as one list (Tutorial 20)
- builds RAG knowledge from your documents and turns it into search tools (Tutorial 21)
- monitors the app itself - tool calls, approvals, traces, logs and running servers - with the same numbers you see in Observability (Tutorial 19, Tutorial 21)
- runs the app's chat as a sub-agent (Tutorial 22)
- ships tools, proxied tools and knowledge as standalone MCP servers with Shipyard and runs them on Docker (Tutorial 19, Tutorial 21)
Every change it makes and every call you mark asks you first in that client, and everything is logged and audited, readable from your AI with the
saip_monitor_*tools and in the Observability dashboards -
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 116 pre-loaded default tools - web, files, GitHub, Wikipedia, weather, finance, geo and Korean services (browse below)
- connect external services in one click with 58 preset MCP server connections - Gmail, Notion, Slack, GitHub, BigQuery, Tavily and more (browse below)
- 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")
- ship what passed as its own MCP server with Shipyard - tools, proxied tools and RAG knowledge in a Docker bundle that runs without the playground
- run every tool in a defense-in-depth GraalVM sandbox with a visible Risk Level (L0-L5), and risk-score every external MCP server you connect (AI Agent Tool Safety)
- see every chat, tool call, vector query and MCP invocation in the fourteen built-in Observability dashboards, down to the span timeline and back to the conversation
Feature pages at a glance
- 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, with an optional bearer token on the built-in
/mcpendpoint. Behind that token the same server offers thesaip_*management tools, so an external AI can operate the app with your approval. - Shipyard: ship Local Pass tools, proxied tools and RAG knowledge as a standalone MCP server in Docker that runs without the playground, on local or remote Docker, behind a bearer token of its own.
- Default MCP Servers: 58 preset external MCP server connections (Gmail, Notion, Slack, GitHub, Tavily, ...) gated on
${ENV_VAR}placeholders. - RAG: upload content, chunk it, enrich it, embed it, then compose a Modular RAG pipeline over it - query rewriting, multi-query expansion, re-ranking, prompt augmentation - and test it against the same executor chat uses.
- 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, dynamic tool discovery, per-turn reasoning effort, document attachments with size-tiered ingest, image attachments as multimodal vision input, review-then-act action cards (email, calendar, map) and clickable file paths, on-device voice input, and rich code/math/diagram rendering. - Observability: fourteen in-app dashboards covering token economics, tool and MCP behavior, RAG quality, host runtime, and a live trace tail.
How it all connects¶
Spring AI Playground is one local app with three roles: an MCP server that publishes tools to your agents at /mcp, an MCP client that reaches external services, and a workbench where you build and vet tools. Your AI clients call its tools over /mcp (Claude Desktop through the mcp-stdio profile) or operate it through the saip_* management tools, and every change that matters comes back to you as an approval question. Tools from the built-in library, Tool Studio and proxied external servers are vetted before an agent can call them (AI Agent Tool Safety), Shipyard ships what passed as a standalone MCP server, and everything that runs lands in Observability. Models run local-first: Ollama by default, OpenAI and OpenAI-compatible runtimes optional.
Mentions and Coverage¶
Introducing the Spring AI Community GitHub Organization - spring.io, October 7, 2025. Listed under Incubating Projects:
Spring AI Playground - Self-hosted web UI for AI experimentation and testing, enabling developers to explore Spring AI capabilities interactively. Led by Jemin Huh.
This Week in Spring - June 2nd, 2026 - spring.io, June 2, 2026. Josh Long in the weekly Spring ecosystem roundup:
the Spring AI Playground seems like a very interesting project indeed
Client-Side Tool Risk Gating for MCP Hosts - OWASP MCP Top 10, merged July 29, 2026. Contributed from this project and accepted as a recommended control, written vendor-neutrally as a host-side pattern, with Spring AI Playground cited as its open-source reference implementation.
The Complete Guide to AI Agent Development with Spring AI 2.0 - Wikibooks, September 17, 2026, in Korean, written by this project's lead maintainer. Its Spring AI Playground appendix introduces the app and connects the book's MCP servers to it; the companion site is free in English and Korean, and the book itself is in Korean.
Also carried on the Spring AI Community project page with the Incubating badge, and listed under UI Clients in awesome-spring-ai. The full record of coverage and ecosystem listings lives on the Mentions page.
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 58 times so you don't have to. The 116 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¶
→ Browse all 116 default tools across Examples (29) · Utilities (26) · Filesystem (18) · Global (21) · Korea (22).
External MCP - one click in the sidebar, fill ${ENV_VAR}, done¶
→ Browse all 58 preset MCP connections across Productivity & Communication (8) · Dev & Project Management (12) · Data & Cloud (18) · Business (12) · Search (6) · Examples (2). New to this surface? Walk through Tutorial 9 - MCP Everything: All 8 Primitives in One Walkthrough.
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.
What the project focuses on now
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, and shipping them with proxied tools and RAG knowledge as standalone MCP servers through Shipyard
- letting an external AI operate the app over MCP through the management tools, with human approval on every change that matters
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.
Further Reading¶
- Getting Started: install the desktop app, configure models, and understand alternative runtimes
- Features: the main product areas and what they do
- Tutorials: follow end-to-end workflows for tools, MCP, vector search, and agentic chat
Architecture pages
- 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
- OWASP MCP Top 10 Coverage: how the shipped controls map to MCP01-MCP10 and where coverage is partial, alongside Client-Side Tool Risk Gating for MCP Hosts, the upstream OWASP recommended control contributed from this project
- Agent Loop: per-turn state, round bounds, and the interceptor chain that governs the Agentic Chat tool-calling loop
- Context Engineering Architecture: how each chat turn's context window is assembled from system prompt, retrieved documents, tools, memory, and per-request options
- AI Agent Observability Architecture: trace pipeline, storage tiers, configuration, and external export paths behind the fourteen dashboards
- Shipyard Architecture: one ship request from three entry points, the three bundle contributions, the fail-closed container and the freshness check
- AI Operations Architecture: how an external AI operates the app over MCP, the one approval gate, the guides the app serves and the audit trail
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.