spring-ai-playground

title: External connections description: Connect Spring AI Playground to your AI client (Claude, Cursor, Codex, VS Code), set up model providers (Ollama, OpenAI), and add external MCP servers.

External connections

Spring AI Playground sits between three kinds of connection - see How it all connects for the picture. This is the practical guide to wiring each one:

the AI clients that consume the built-in MCP server,
the model providers it runs on, and
the external MCP servers it proxies.

Connect your AI clients

The app publishes a built-in MCP server in the same process as the UI:

Streamable HTTP - http://localhost:8282/mcp (change the port with SERVER_PORT)
stdio - start with the mcp-stdio profile (SPRING_PROFILES_INCLUDE=mcp-stdio) for hosts that spawn a local process; see Alternative Runtimes

Most clients connect over Streamable HTTP. Drop the matching config below in - it points at the default endpoint and uses spring-ai-playground as the server name (rename it to anything you like).

{ .provider-icon } Claude Code - run (docs):

claude mcp add --transport http spring-ai-playground http://localhost:8282/mcp

{ .provider-icon } Cursor - ~/.cursor/mcp.json (docs):

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

{ .provider-icon } VS Code (Copilot) - .vscode/mcp.json (docs):

{
  "servers": {
    "spring-ai-playground": { "type": "http", "url": "http://localhost:8282/mcp" }
  }
}

{ .provider-icon } Codex (CLI) - ~/.codex/config.toml (docs):

[mcp_servers.spring_ai_playground]
url = "http://localhost:8282/mcp"

{ .provider-icon } opencode - ~/.config/opencode/opencode.json (docs):

{
  "mcp": {
    "spring-ai-playground": { "type": "remote", "url": "http://localhost:8282/mcp", "enabled": true }
  }
}

{ .provider-icon } OpenClaw - openclaw.json (docs):

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

Cline, Windsurf, Zed, and other MCP hosts follow the same pattern - add a Streamable HTTP (or SSE) server pointing at http://localhost:8282/mcp. Check your client’s MCP docs for the exact field names.

{ .provider-icon } Claude Desktop. Its custom connectors (Settings -> Connectors) connect from Anthropic’s cloud, so they cannot reach a localhost server. To use the playground from Claude Desktop, either run it as a stdio server with the mcp-stdio profile and add it to claude_desktop_config.json, or expose the HTTP endpoint through a tunnel. See Build custom connectors via remote MCP.

Once connected, the client sees your Local-Pass tools - and any proxied or composed external tools - in its tools/list.

Connect model providers

Spring AI Playground is provider-agnostic, but the runtime defaults are tuned for a local-first Ollama experience. The app is currently centered on three runtime paths: Ollama, OpenAI, and OpenAI-compatible servers. (Spring AI itself supports many more providers - Anthropic, Google, Amazon, and others - but those are not part of the default desktop flow; you would fork and rebuild for them. See the Spring AI Chat Models reference.)

{ .provider-icon } Ollama (default)

The default profile is ollama - it serves both chat and embeddings locally, with no API key. Defaults:

chat model: qwen3.5:2b
embedding model: qwen3-embedding:0.6b
selectable chat models: qwen3.5:2b, qwen3.5:9b, qwen3.6:35b, gemma4:e4b, gpt-oss:20b, deepseek-r1:8b

Missing models are pulled automatically when first used; the selectable list controls the in-app model picker. In Docker, point at a host Ollama with SPRING_AI_OLLAMA_BASE_URL.

{ .provider-icon } OpenAI

provide OPENAI_API_KEY,
activate the openai profile (or pick the OpenAI setting in the desktop launcher),
launch.

Where you set the key depends on your install path: in the desktop app use the launcher’s Environment Variables section and pick the OpenAI config type; for Docker or source see Alternative Runtimes -> Switching to OpenAI.

OpenAI-compatible servers { #switching-to-openai-compatible-servers }

Point the openai provider at any server that exposes an OpenAI-style /v1 API - LM Studio, vLLM, llama.cpp, TabbyAPI, Ollama, and others:

spring:
  ai:
    model:
      chat: openai
      embedding: ollama
    openai:
      api-key: "not-used"              # a real key if the server requires auth
      base-url: "http://localhost:1234/v1"
      chat:
        options:
          model: "your-loaded-model"
          # extra-body: { top_p: 0.95, repetition_penalty: 1.1 }   # provider-specific, optional

Server	`base-url`	notes
{ .provider-icon } Ollama (compatible mode)	`http://localhost:11434/v1`	local, no key
{ .provider-icon } LM Studio	`http://localhost:1234/v1`	`model` = the loaded model
{ .provider-icon } vLLM	`http://localhost:8000/v1`	`model` = the HF repo id
{ .provider-icon } llama.cpp	`http://localhost:8080/v1`	accepts `extra-body` (e.g. `top_k`)
{ .provider-icon } TabbyAPI	`http://localhost:5000/v1`	set a real `api-key`

Other useful keys: completions-path (only if the server deviates from the standard chat-completions path), http-headers (custom auth/transport), and maxTokens / maxCompletionTokens (use one, not both). Test the target with a /v1/models request first to confirm the exact model names and endpoint shape. Full field reference: Spring AI OpenAI Chat.

Embeddings and RAG. If you change the embedding model after documents are already indexed, existing vector data can become inconsistent - re-import or rebuild the vector database before trusting retrieval again.

Connect external MCP servers

The app ships a curated catalog of preset MCP servers (Gmail, Slack, GitHub, Notion, Stripe, BigQuery, and more). On the MCP Server screen, find the entry in the Inactive MCP section, click it to prefill the form, fill any ${ENV_VAR} placeholders, and Save & Connect. See Default MCP Servers for the full per-category browse.

For a server that is not in the catalog, use Add Custom Server on the same screen: pick the transport (Streamable HTTP / SSE / stdio), enter the URL or command, and set custom headers, OAuth 2.1, or ${ENV_VAR} substitution as needed. See MCP Server -> Add Custom Server.

Whatever you connect, you can re-publish it - proxy and compose its tools onto your own built-in server. Re-published tools are governed exactly like the ones you author: each gets a Risk Level score plus a description-poisoning scan (AI Agent Tool Safety, MCP Server Safety), a per-tool human-in-the-loop approval gate (Human-in-the-Loop), and full Observability (dashboards) - even for a server you did not build. You set the risk cap and approval per tool on the MCP Server Proxy, so your AI clients reach everything on one governed endpoint.

This site is open source. Improve this page.