Tutorials¶

These seventeen tutorials walk you from creating a single tool to composing chains over the bundled default catalog, with optional deep-dives off the main path - the MCP protocol surface, re-publishing tools through the MCP Server Proxy, gating tool calls behind human approval, turning a Prompt Library template into a reusable preset, uploading a file into chat for an agent to analyze, attaching an image for a vision model to see, and investigating documents with a filesystem pipeline - and a capstone that ships one API all the way to a running MCP server. They follow the natural product workflow: build → validate → ground → compose.

The shipped chat default is qwen3.5:4b - fast, vision-capable, fine for the early tutorials. Switch to qwen3.5:9b or gemma4:e4b when you reach tutorials 4-7, where tool-calling reliability matters. Embeddings use qwen3-embedding:0.6b throughout. See Picking a model for the tradeoffs.

How these tutorials connect¶

flowchart LR
  T1["1. Author a Tool<br/>Tool Studio"]
  T2["2. Connect MCP<br/>MCP Server"]
  T3["3. Index a Doc<br/>Vector Database"]
  T4["4. Chat + Tools<br/>Agentic Chat"]
  T5["5. Chat + RAG<br/>Agentic Chat"]
  T6["6. Tools + RAG<br/>Agentic Chat"]
  T7["7. Tool Chain<br/>Weather → Slack"]
  T8["8. Default Tool Recipes<br/>JS-action chains"]
  T9["9. MCP Everything<br/>All 8 Primitives"]
  T10["10. Server Proxy<br/>Re-publish a tool"]
  T11["11. Approve in Chat<br/>Human-in-the-Loop"]
  T12["12. Template to Preset<br/>Prompt Library"]
  T13["13. Upload & Analyze<br/>requestFileUpload"]
  T14["14. Attach an Image<br/>native vision input"]
  T15["15. Investigate Documents<br/>Unix-pipeline tools"]
  T16["16. API to MCP Server<br/>publish + gate + ship"]
  T17["17. Attach a Document<br/>instant RAG in chat"]
  T1 --> T2
  T2 --> T4
  T3 --> T5
  T4 --> T6
  T5 --> T6
  T6 --> T7
  T7 --> T8
  T2 -. deep dive .-> T9
  T2 -. proxy .-> T10
  T4 -. approve .-> T11
  T4 -. preset .-> T12
  T4 -. upload .-> T13
  T4 -. vision .-> T14
  T13 -. pipeline .-> T15
  T5 -. attach .-> T17
  T8 ==> T16
  T11 -. gate .-> T16
  classDef build fill:#eef2ff,stroke:#3F51B5,color:#1e1b4b
  classDef validate fill:#ecfdf5,stroke:#10b981,color:#064e3b
  classDef ground fill:#fff7ed,stroke:#f59e0b,color:#7c2d12
  classDef compose fill:#fdf2f8,stroke:#e11d48,color:#831843
  classDef bonus fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95
  classDef ship fill:#fef2f2,stroke:#b91c1c,color:#7f1d1d
  class T1 build
  class T2 validate
  class T3 ground
  class T4,T5,T6,T7,T8 compose
  class T9,T10,T11,T12,T13,T14,T15,T17 bonus
  class T16 ship

Tutorials 1-3 produce reusable assets (a tool, an MCP connection, an indexed document). Tutorials 4-8 compose those assets in chat (4-6) and as code-level chains over the bundled default catalog (7-8). Tutorial 9 is an optional deep dive off Tutorial 2 - activate MCP Everything from the Default MCP Servers and exercise every Inspector primitive (Tools / Resources / Prompts / Ping / Notifications / Roots / Sampling / Elicitation) end-to-end. Tutorial 10 is a second deep dive off Tutorial 2 - re-publish a connected server's tool through the built-in MCP Server Proxy so chat and external clients can call it. Tutorial 16 is the capstone: it takes a public REST API through Tool Studio, an approval gate, the built-in MCP server, and finally into a Docker container that any MCP client can connect to. Each tutorial is independently runnable in 4-25 minutes; the full main sequence takes about 65 minutes, plus ~50 minutes for the deep dives (MCP Everything, Server Proxy, Human-in-the-Loop approval, the file and image attachments, and the document pipeline) and 25 minutes for the capstone.

What you'll need

Spring AI Playground running on http://localhost:8282. Follow Getting Started first if you haven't.

Ollama running, with qwen3.5:9b and qwen3-embedding:0.6b pulled.

ollama pull qwen3.5:9b
ollama pull gemma4:e4b
ollama pull qwen3-embedding:0.6b

For Tutorial 7 only: SLACK_WEBHOOK_URL set in the launcher's Environment Variables.

Tutorial list¶

1. Author and Validate a Tool

getWeather from Starter 5 → Local Pass → MCP exposure.
8 min · ★☆☆ · Tool Studio + MCP Server
2. Connect an External MCP Server

Streamable HTTP / STDIO / SSE / OAuth 2.1, validated in the Inspector.
8 min · ★★☆ · MCP Server
3. Index a Document for RAG

Upload → pick a reader → chunk → embed → similarity-search validate.
7 min · ★☆☆ · Vector Database
4. Chat With Tools

Real tool call from a chat turn - see plan → call → answer.
5 min · ★★☆ · Agentic Chat
5. Chat With RAG

Grounded chat on the indexed document, then the same question through a staged pipeline.
7 min · ★★☆ · Agentic Chat + Vector Database
6. Tools and RAG Together

One turn that retrieves chunks AND calls a tool - full composition.
6 min · ★★★ · Agentic Chat (full)
7. Weather to Slack - A Two-Tool Chain

getWeather → sendSlackMessage in one prompt - the agent loop.
4 min · ★★★ · Agentic Chat
8. Default Tool Recipes

Five new custom tools, each chaining default-tool helpers inside one JS action.
20 min · ★★★ · Tool Studio + Agentic Chat
9. MCP Everything - All 8 Primitives

Activate the Default MCP Servers's reference test server and exercise every Inspector primitive - Tools, Resources, Prompts, Ping, Notifications, Roots, Sampling, Elicitation - in one sitting. OS-specific Node install or Docker alternative.
12 min · ★★☆ · MCP Server (catalog + Inspector) · deep dive
10. Proxy an MCP Server

Re-publish a whole MCP server - or a curated mix of several - through the built-in server, each tool risk-capped, HITL-gated, and logged; then call it from chat and external /mcp clients.
8 min · ★★☆ · MCP Server · deep dive
11. Approve a Tool in Chat

Turn on human-in-the-loop approval, then approve or decline a tool call live in chat.
6 min · ★★☆ · Tool Studio + Agentic Chat · deep dive
12. Build a Preset from a Template

Fill a template's variables and save the assembled prompt as a named, reusable preset with the Save as preset dialog.
6 min · ★★☆ · Agentic Chat · deep dive
13. Upload and Analyze a File

Upload a CSV or Excel file with the interactive requestFileUpload tool, then have the agent read and analyze it.
7 min · ★★☆ · Agentic Chat · deep dive
14. Attach and Analyze an Image

Attach an image to the chat and have a local vision model analyze it, then re-reference it later with describeImage.
5 min · ★☆☆ · Agentic Chat · deep dive
15. Investigate Documents with a Pipeline

Upload a contract with the Document detective preset and pull facts out of it the Unix-pipeline way - find, grep, slice, quote with line numbers.
6 min · ★★☆ · Agentic Chat · deep dive
16. From a Public API to Your Own MCP Server

Wrap an API you already have credentials for, gate it behind human approval, then hand the same configuration to Docker so any MCP client can call it.
25 min · ★★★ · Tool Studio + Agentic Chat + MCP Server + Docker · capstone
17. Attach a Document and Ask

Drop a document on the chat prompt, get a summary and pinpoint answers with no indexing step, then register it in the Vector Database with one click.
12 min · ★☆☆ · Agentic Chat + Vector Database · deep dive

Picking a model¶

Tool calling and tool chaining quality depend heavily on the model. The selectable list in Agentic Chat → Settings → Model is driven by application.yaml's playground.chat.models. The shipped default is the small one - start there, and only upgrade if a tool turn comes back empty.

qwen3.5:4b (default)qwen3.5:9bgemma4:e4bgpt-oss:20b

The shipped default. 3.4 GB. Fast on Apple Silicon, and the smallest build that ships vision tensors, so image attachments work out of the box. Use this for the chat sanity check before wiring up tools or RAG. Tool calling is best-effort - if a tool turn comes back empty, that is the signal to upgrade, not to rewrite the prompt.

6.6 GB. Stronger tool calling and multi-turn reasoning. The first upgrade target when qwen3.5:4b skips a tool call.

9.6 GB. Strongest natural-language quality. Pick this for tutorial 7 (multi-step tool chains) where the model has to reason about a tool result rather than just call it.

13 GB. OpenAI's open-weights reasoning model. A good cross-check when you suspect a result depends heavily on which model family you picked.

Where the model selector lives

Open Agentic Chat, click the gear icon at the top right, change Model, then click Apply & New Chat. The chat header reflects the change.

Tutorials¶

How these tutorials connect¶

Tutorial list¶

Picking a model¶

Further Reading¶