home / mcp / spring ai playground mcp server

Spring AI Playground MCP Server

Provides a built‑in MCP server to connect, inspect, and execute tools via a streamable HTTP endpoint.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jm-lab-spring-ai-playground": {
      "url": "http://localhost:8282/mcp"
    }
  }
}

You leverage a built‑in MCP server to connect, inspect, and execute tools exposed by the Spring AI Playground. This enables you to run tool-enabled workflows and agent-like reasoning via a single, live endpoint without redeploying or restarting your host application, making it ideal for rapid prototyping and integration testing.

How to use

Connect your MCP client to the built‑in server at http://localhost:8282/mcp. Use the MCP Inspector to browse available tools, view their schemas, and validate execution behavior. Publish and test tools created in Tool Studio in real time; any tool registered to the default MCP server spring-ai-playground-tool-mcp becomes immediately usable by MCP clients. In Agentic workflows, you can mix RAG context from your Vector Database with tool calls via MCP to perform actions and fetch live data.

How to install

Prerequisites: Install Java 21 or later, install Docker for containerized runs, and install Ollama if you plan to use local LLMs and embeddings.

Option A — Running with Docker (Recommended) Start by building the production image and then running the container.

./mvnw spring-boot:build-image -Pproduction -DskipTests=true \
  -Dspring-boot.build-image.imageName=jmlab/spring-ai-playground:latest

Next, start the container and expose the MCP endpoint. This runs the app in the background and maps port 8282 to your host, using the built image and a mounted volume for persistence.

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:/home \
--restart unless-stopped \
jmlab/spring-ai-playground:latest

Access the application in your browser at http://localhost:8282.

Running Docker cleanup

If you need to stop and remove the setup, run these commands to stop, remove the container, image, and volume.

docker stop spring-ai-playground
 docker rm spring-ai-playground
 docker rmi jmlab/spring-ai-playground:latest
 docker volume rm spring-ai-playground

Option B — Running locally (Optional)

Build and run the application directly with Maven. This is useful if you prefer a local Java run without Docker.

./mvnw clean install -Pproduction -DskipTests=true
./mvnw spring-boot:run

PWA installation

Spring AI Playground ships with Progressive Web App (PWA) capabilities. Install it as a standalone app on your device for a native app experience after completing either Docker or Local installation steps.

Security and transport notes

The built‑in MCP server supports multiple transports and can stream responses. If you plan to test MCP STDIO transport, prefer running locally rather than in Docker, since containerized environments may not reliably support process‑to‑process communication.

Configuration overview

Spring AI Playground uses Ollama by default for local LLMs and embeddings. You can switch providers or configure OpenAI‑compatible servers by adjusting runtime profiles and environment variables, as described in model and OpenAI configuration sections.

Usage notes for developers

Tools created in Tool Studio are dynamically registered to the built‑in MCP server and become available without restarts. Use the Tool Inspector to validate tool schemas and execution, and publish changes with Test & Update Tool to apply them immediately.

Available tools

googlePseSearch

Search the web using Google Programmable Search Engine (PSE). Requires ${GOOGLE_API_KEY} and ${PSE_ID} to run in Tool Studio tools.

extractPageContent

Extracts and cleans the main textual content from a given web page URL, removing ads, navigation, and scripts for clean data.

buildGoogleCalendarCreateLink

Generates a Google Calendar Add Event URL with prefilled fields for quick event creation.

sendSlackMessage

Send messages to Slack channels using an Incoming Webhook URL. Requires ${SLACK_WEBHOOK_URL}.

openaiResponseGenerator

Generate AI responses via the OpenAI API. Requires an API key.

getWeather

Get the current weather for a location by querying wttr.in JSON API and return a concise summary.

getCurrentTime

Return the current time in ISO 8601 format.