Safe local execution layer for AI agent tools. Build and test-run MCP tools (no pass, no run), serve them from a built-in MCP server, and use them in Agentic Chat with RAG, human-in-the-loop approval, and built-in observability. Cross-platform desktop app powered by Spring AI.
curl -fsSL https://cookapps.net/api/skills/install?skills=••••••• | nodeSafe 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.
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 spanning Overview, Tokens & Cost, AI Models, Tool Studio, MCP Servers, MCP Inspector, Vector Database, Agentic Chat, Safety, Host, Ollama, Web Application, Logs, and Traces, backed by a ring buffer with dated disk persistence. Drill from a row into the trace timeline and raw spans, jump to the conversation thread, and deep-link back into Agentic Chat - so the tools you let an agent call are also the tools you can see in detail after the fact.
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.
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
ChatGPT ships and runs an MCP server for you · every risky step waits for your approval · 100% local

Spring AI Playground demo - ChatGPT writes and publishes a tool, ships a new version of a knowledge MCP server, and every destructive step pauses at an approval card for a person
▶ Watch: An AI Ships and Runs an MCP Server (2.5 minutes) · It Asks Before It Deletes (1 minute) · 30-second trailer · full demo series (YouTube playlist) · more on the docs site
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.
"a very interesting project indeed" - Josh Long, This Week in Spring
The download page detects your platform and offers the matching installer, then confirms the filename, size, and default save path before the download starts. Direct links: Windows - macOS Apple Silicon - macOS Intel - Linux DEB - Linux RPM. Or browse every asset on the Releases page.
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:
>
- 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.debor.rpmpackage, you usually only need to complete the normal package-install confirmation steps.
>
For more detailed platform guidance, see the Getting Started guide.
Every release ships with a matching .sha256 checksum file and a Sigstore SLSA build provenance attestation. See Verify Your Download in the docs for the exact shasum, Get-FileHash, and gh attestation verify commands.
Free code signing provided by SignPath.io, certificate by SignPath Foundation. See our Code Signing Policy for how releases are built, signed, and verified.
Windows installers are signed once the SignPath Foundation release certificate is issued (targeted for 1.0.0); until then they ship unsigned, so verify them with the published checksums and provenance attestations.
The desktop launcher handles first-run setup on one screen - provider config, Default MCP Tools curation, and JVM/environment cards - and includes an Ollama model manager to review, search, and download models. See Getting Started and Model Configuration.
Unlock application details to view installation, configuration, and workflow guides.
/mcp once. It reads the guides, start prompts and example tools the app serves over MCP, with this app's own sandbox limits filled in, and, through the saip_* management tools, does the work itself: Every change it makes and every call you mark asks you first in your client, and everything is logged and audited, readable from your AI with the saip_monitor_* tools and in the app's Observability dashboards.
${ENV_VAR} placeholders so disabled servers can't be activated without setup. One-click activation from the sidebar once the required env vars exist. Browse the full list in the Default MCP Catalog./mcp endpoint - compose multiple servers into one surface callable from Agentic Chat, the Inspector, and external MCP clients, each gated by per-tool human-in-the-loop.search_ tool) and export a self-contained server bundle - a manifest with content hashes, Dockerfile / compose / README, and a server.json for the MCP registry. The bundle boots fail-closed, serves exactly what the manifest lists behind a bearer token of its own (SAIP_MCP_AUTH_TOKEN), enforced the same way as on the built-in server, and carries each tool's approval gate with it. Built servers are managed in one place: Run on local or remote Docker, status and logs, an Out of date banner when a source changed after shipping, and a Connect panel with one-click deep links and copy-ready snippets for common MCP clients.default-tools-preference.json - pick a preset (Starter 5, Dev Essentials, Korea Toolkit (free), File Toolkit, Everything) plus optional per-tool include / exclude rules to decide which bundled tools the built-in MCP server exposes at boot; Tool Studio's Built-in MCP Server Native Tools drawer then adjusts that exposure tool by tool.fetch, rooted safety.fs, statement and wall-clock limits, with a visible per-tool Risk Level (L0-L5) computed from the declared capabilities - surface every tool's blast radius before you publish it.${ENV_VAR} placeholders that resolve at tool / MCP load time. SecretMasking redacts any resolved value (≥ 4 characters) from error logs and console output. When OS-backed secure storage is unavailable, the app clearly warns before falling back to plain-text local storage.spring.ai.playground.mcp-server.auth-token for declarative deployments; /mcp then requires the token (a shared secret by design; outbound connections to external MCP servers keep full OAuth 2.1). Boot with spring.ai.model.chat=none / spring.ai.model.embedding=none to run the tool runtime and MCP server with no model provider at all. Set SPRING_AI_PLAYGROUND_UI_ENABLED=false to run the app, or a server shipped by Shipyard, as a headless MCP server with every screen answering 404.{{variable}} templates, per-turn reasoning effort (Off/Low/Medium/High), a configurable per-chat memory window, dynamic tool discovery, document attachments routed by size into conversation-scoped RAG, image attachments as native multimodal input for vision models, review-then-act action cards (email, calendar, map), clickable file paths, on-device voice input, and rich rendering of syntax-highlighted code, KaTeX math, and Mermaid diagrams. See Agentic Chat.The intended workflow is practical and composable:
Ships with a bundled catalog of default tools - web fetch, datetime, math, security, encoding, crypto, filesystem, GitHub, Wikipedia, weather, finance, geo, and a Korean-domain bundle (Upbit, Bithumb, Naver, Kakao, KMA, KOFIC, KRX, data.go.kr keychain) - searchable and filterable in the Default Tools directory.
Plus a preset catalog of external MCP servers - Gmail, Notion, Slack, GitHub, Linear, Atlassian, Tavily, Firecrawl, Microsoft Teams, Sentry, and more - grouped by category with ${ENV_VAR} placeholders so disabled servers can't be activated without setup. Browse the full list in the Default MCP Catalog.
More coverage and ecosystem listings: Mentions.
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, and even fewer leave a clear trail of what each tool actually did after it ran. Spring AI Playground treats both as part of safe local execution - Local Pass at the gate, Observability dashboards on the inside.
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.
Spring AI Playground started as a way to explore Spring AI; as Spring AI and the ecosystem moved toward agents and MCP, it grew into a safe local execution layer for the tools agents call.
It also doubles as a working reference implementation of the Spring AI framework - every surface in the app maps to a real Spring AI API, so you can use this repo as an end-to-end example of how those pieces fit together.
SpringAiPlaygroundRagAdvisor that runs the selected Modular RAG pipeline, an AttachedDocumentRagAdvisor for conversation attachments, and the Tool Calling pipeline are composed through ChatClient.builder().spring-ai-starter-mcp-client connects to the external MCP servers in the preset catalog and to the built-in MCP server in the same JVM, while spring-ai-starter-mcp-server-webmvc publishes every Local-Pass tool you author through the spring-ai-playground-built-in-mcp connection on /mcp.ToolCallback** - Tool Studio tools and external MCP tools both run through a single AgentLoopManager (the app's ToolCallingManager, adding per-turn round bounds and the human-in-the-loop gate), with LoggingMcpToolCallback adding correlation ids and secret masking around every call.SimpleVectorStore plus the Spring AI document readers (Tika, PDF, Markdown, HTML, JSON, text), TokenTextSplitter, and the keyword / summary metadata enrichers power the Vector Database indexing flow, and the Pipeline Studio composes the framework's own pre-retrieval / retrieval / post-retrieval / generation modules into saved pipelines that Agentic Chat runs through the same executor.ObservationRegistry is wired into ToolCallingManager and SimpleVectorStore, so spans emitted by Spring AI's semantic conventions (gen_ai.client.operation, spring.ai.chat.client) flow straight into the in-app Observability dashboards alongside chat-client spans.The version tracks the latest Spring AI release; use it as a reference when integrating these same features into your own Spring Boot app.
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):
docker run -p 8282:8282 -v spring-ai-playground:/root ghcr.io/spring-ai-community/spring-ai-playground./mvnw -Pproduction spring-boot:runFor 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):
docker run -i --rm -e SPRING_PROFILES_INCLUDE=mcp-stdio -v spring-ai-playground:/root ghcr.io/spring-ai-community/spring-ai-playground. Add -p 8282:8282 if you also want browser access to the Vaadin Inspector alongside the stdio channel.spring-ai-playground-*.jar from Releases (or ./mvnw -Pproduction package) and run SPRING_PROFILES_INCLUDE=mcp-stdio java -jar spring-ai-playground-*.jar. No Docker required, ideal for Java/Spring developers and CI integrations.Full setup details for both modes live in Getting Started: Alternative Runtimes.
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, runtime exposure, and shipping 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.
Please read this section before opening issues or submitting contributions. This section sets the scope: what we accept, what we do not, and what is planned. CONTRIBUTING.md explains how to contribute within it, step by step.
spring-projects repositories. PRs that add third-party ranking, leaderboard, or referral badges are closed without further discussion. Being indexed by a directory does not require a badge, and we are glad to stay listed either way.Advance notice: we plan to open one kind of external contribution, local tools built in Tool Studio, written by a person, an AI agent, or both. A tool must earn its Local Pass in the app first. CI then re-runs the Local Pass, an LLM reviews the PR, and only then does the maintainer review and merge it. Accepted tools ship with the next release as a Community bundle.
The acceptance rules, the CI and the review pipeline are being built now, so this is not open yet; please do not send tool PRs until it is. The plan, the draft rules and how to prepare a tool today are in CONTRIBUTING.md.
Pick the right channel:
docs/ (typos, errors, broken links); open a Discussion first for README changes or new sectionsWe 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; CONTRIBUTING.md lists what each one needs. For anything else, please open a Discussion first - but be aware we may not act on it given current capacity.
The official build sends anonymous usage data (page views, feature-usage events such as
which model, preset, or tool kind is used, device/browser info) to the maintainer's
Google Tag Manager / Google Analytics account so the most-used features can be
prioritized. It is content-free: no prompts, documents, file names, URLs, or API keys,
and names of things you create yourself (tools, presets, custom MCP servers) are masked.
The complete event table is in the
and every sender is auditable in code (search for UsageEventTracker). IPs are
anonymized by Google. Development-mode runs never send telemetry. The same opt-out
switch applies to both the web app and every desktop launcher window (splash,
server-splash, config editor, Ollama manager):
mvn**: SPRING_AI_PLAYGROUND_TELEMETRY_ENABLED=falseSPRING_AI_PLAYGROUND_TELEMETRY_ENABLED=false before launchingthe app (the launcher forwards this env var to every window and to the bundled Spring
process)
-Dspring.ai.playground.telemetry.enabled=false as a JVM argIf you self-host this project for EU users, adding cookie consent on top is the
operator's responsibility under GDPR.
These are the next pieces we plan to add while keeping the project focused on practical, reusable tool execution. Track day-to-day progress in the [CHANGELOG [Unreleased] section](CHANGELOG.md#unreleased).
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Get instant access to complete setup guides, repository source code, and integration assets.