docs: fix broken documentation links in README

README.md

@@ -14,7 +14,7 @@ Just ask your AI assistant:
 
 > *"Find sci-fi movies with 'star wars' in the title released after 2000, show me the genre breakdown, and sort by relevance."*
 
-This Spring AI [Model Context Protocol (MCP)](https://spec.modelcontextprotocol.io/) server exposes Solr operations as tools that any MCP-compatible AI client (Claude Desktop, Claude Code, VS Code/Copilot, Cursor, JetBrains) can invoke.
+This Spring AI [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server exposes Solr operations as tools that any MCP-compatible AI client (Claude Desktop, Claude Code, VS Code/Copilot, Cursor, JetBrains) can invoke.
 
 ## Quick start
 
@@ -59,11 +59,12 @@ Add the server to your MCP client. For **Claude Desktop**, edit
 ```
 
 Using a different client, or want STDIO/HTTP/Docker options? See the per-client guides:
-**[Claude Code](docs/site/content/pages/mcp/clients/claude-code.md)** ·
-**[VS Code / Copilot](docs/site/content/pages/mcp/clients/vs-code.md)** ·
-**[Cursor](docs/site/content/pages/mcp/clients/cursor.md)** ·
-**[JetBrains](docs/site/content/pages/mcp/clients/jetbrains.md)** ·
-**[MCP Inspector](docs/site/content/pages/mcp/clients/mcp-inspector.md)**.
+**[Claude Desktop](docs/clients/claude-desktop.md)** ·
+**[Claude Code](docs/clients/claude-code.md)** ·
+**[VS Code / Copilot](docs/clients/vs-code.md)** ·
+**[Cursor](docs/clients/cursor.md)** ·
+**[JetBrains](docs/clients/jetbrains.md)** ·
+**[MCP Inspector](docs/clients/mcp-inspector.md)**.
 
 #### 4. Try it out
 
@@ -146,13 +147,13 @@ The server reads configuration from environment variables. The essentials:
 | `SOLR_URL` | Solr base URL | `http://localhost:8983/solr/` |
 | `PROFILES` | Transport mode: `stdio` (default, for Claude Desktop) or `http` (remote / multi-client) | `stdio` |
 
-Running in **HTTP mode** — OAuth2, CORS, and the `HTTP_SECURITY_ENABLED` toggle (secured by default) — is covered in the [security docs](docs/security/). Tracing and metrics env vars (`OTEL_SAMPLING_PROBABILITY`, `OTEL_TRACES_URL`) are covered in [Observability](docs/site/content/pages/mcp/observability.md).
+Running in **HTTP mode** — OAuth2, CORS, and the `HTTP_SECURITY_ENABLED` toggle (secured by default) — is covered in the [security docs](docs/security/). Tracing and metrics env vars (`OTEL_SAMPLING_PROBABILITY`, `OTEL_TRACES_URL`) are covered in [Observability](docs/observability.md).
 
 ## Documentation
 
 **Using it**
-- [Quick start](docs/site/content/pages/mcp/quick-start.md) · [Client setup](docs/site/content/pages/mcp/clients/) — Claude Desktop, Claude Code, VS Code, Cursor, JetBrains, MCP Inspector
-- [Observability](docs/site/content/pages/mcp/observability.md) — OpenTelemetry traces, metrics, logs
+- [Quick start](#quick-start) · [Client setup](docs/clients/) — Claude Desktop, Claude Code, VS Code, Cursor, JetBrains, MCP Inspector
+- [Observability](docs/observability.md) — OpenTelemetry traces, metrics, logs
 - Security: [Deployment model (single-tenant)](docs/security/deployment-model.md) · [STDIO model](docs/security/stdio.md) · [HTTP model](docs/security/http.md) · OAuth2 setup: [Auth0](docs/security/auth0.md) · [Keycloak](docs/security/keycloak.md)
 
 **Developing it**

docs/clients/README.md

@@ -0,0 +1,19 @@
+# Client Setup Guides
+
+Per-client instructions for connecting an MCP client to the Solr MCP Server.
+Each guide covers the transports the client supports: **STDIO** (the server
+runs as a local subprocess — JAR or Docker) and **HTTP** (connect to a running
+server's streamable HTTP endpoint at `http://localhost:8080/mcp`).
+
+| Client | Guide |
+|--------|-------|
+| Claude Desktop | [claude-desktop.md](claude-desktop.md) |
+| Claude Code | [claude-code.md](claude-code.md) |
+| VS Code / GitHub Copilot | [vs-code.md](vs-code.md) |
+| Cursor | [cursor.md](cursor.md) |
+| JetBrains IDEs | [jetbrains.md](jetbrains.md) |
+| MCP Inspector | [mcp-inspector.md](mcp-inspector.md) |
+
+Before connecting, start Solr and build the server — see the
+[Quick start](../../README.md#quick-start). For OAuth2 on the HTTP transport,
+see the [security docs](../security/).

docs/clients/claude-code.md

@@ -0,0 +1,111 @@
+# Claude Code
+
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's CLI tool for Claude. It supports MCP servers via the `claude mcp add` command or a `.mcp.json` project file.
+
+***
+
+## CLI Syntax ##
+
+The general form of `claude mcp add` is (see [Claude Code MCP docs](https://code.claude.com/docs/en/mcp)):
+
+```bash
+claude mcp add [options] <name> <commandOrUrl> [args...]
+```
+
+The server `<name>` comes first. For a **STDIO** server, pass any `-e KEY=value` options (repeatable) after the name, then `--`, then the launch command. The `--` stops Claude Code from reparsing the server's own flags as its own options, and `-e` stops consuming tokens at the `--`:
+
+```bash
+claude mcp add <name> -e KEY=value -- <command> [args...]
+```
+
+For an **HTTP** server, no `--` is needed — pass the URL with `--transport http`:
+
+```bash
+claude mcp add --transport http <name> <url>
+```
+
+***
+
+## STDIO Mode (Recommended) ##
+
+### CLI ###
+
+```bash
+# JAR
+claude mcp add solr-mcp \
+    -e SOLR_URL=http://localhost:8983/solr/ \
+    -- java -jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar
+
+# Docker (local image — build first with ./gradlew jibDockerBuild)
+claude mcp add solr-mcp \
+    -- docker run -i --rm -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+    solr-mcp:latest
+```
+
+### `.mcp.json` ###
+
+Add to your project root:
+
+**JAR:**
+
+```json
+{
+  "mcpServers": {
+    "solr-mcp": {
+      "type": "stdio",
+      "command": "java",
+      "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+      "env": { "SOLR_URL": "http://localhost:8983/solr/" }
+    }
+  }
+}
+```
+
+**Docker (local image):**
+
+```json
+{
+  "mcpServers": {
+    "solr-mcp": {
+      "type": "stdio",
+      "command": "docker",
+      "args": ["run", "-i", "--rm",
+               "-e", "SOLR_URL=http://host.docker.internal:8983/solr/",
+               "solr-mcp:latest"]
+    }
+  }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the `args` array.
+
+***
+
+## HTTP Mode ##
+
+Start the server in HTTP mode first (`PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar`, or `PROFILES=http ./gradlew bootRun`), then:
+
+### CLI ###
+
+```bash
+claude mcp add --transport http solr-mcp http://localhost:8080/mcp
+```
+
+### `.mcp.json` ###
+
+```json
+{
+  "mcpServers": {
+    "solr-mcp": {
+      "type": "http",
+      "url": "http://localhost:8080/mcp"
+    }
+  }
+}
+```
+
+### Secured HTTP (OAuth2) ###
+
+Claude Code detects the OAuth2 challenge from the server and initiates the authorization flow automatically. The configuration is the same as unsecured HTTP.
+
+See the [HTTP security model](../security/http.md) for server-side OAuth2 setup.

docs/clients/claude-desktop.md

@@ -0,0 +1,107 @@
+# Claude Desktop
+
+[Claude Desktop](https://claude.ai/download) is Anthropic's desktop application for Claude. It supports MCP servers via STDIO and HTTP transports.
+
+### Configuration File
+
+* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Restart Claude Desktop after any configuration change.
+
+***
+
+## STDIO Mode (Recommended) ##
+
+STDIO mode communicates via stdin/stdout. This is the simplest setup for local use.
+
+### JAR ###
+
+Requires Java 25+ and a [built JAR](../../README.md#quick-start) (`./gradlew build`).
+
+```json
+{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "java",
+      "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+      "env": {
+        "SOLR_URL": "http://localhost:8983/solr/"
+      }
+    }
+  }
+}
+```
+
+### Docker (local image) ###
+
+Build the image first: `./gradlew jibDockerBuild`
+
+```json
+{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm",
+               "-e", "SOLR_URL=http://host.docker.internal:8983/solr/",
+               "solr-mcp:latest"]
+    }
+  }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the `args` array.
+
+***
+
+## HTTP Mode ##
+
+HTTP mode connects to a running MCP server via REST endpoints. Start the server first, then configure Claude Desktop to connect using `mcp-remote`.
+
+### Start the Server ###
+
+```bash
+# JAR
+PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar
+
+# Or Gradle
+PROFILES=http ./gradlew bootRun
+
+# Or Docker (local image)
+docker run -p 8080:8080 --rm \
+    -e PROFILES=http \
+    -e SOLR_URL=http://host.docker.internal:8983/solr/ \
+    solr-mcp:latest
+```
+
+### Configure Claude Desktop ###
+
+```json
+{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://localhost:8080/mcp"]
+    }
+  }
+}
+```
+
+### Secured HTTP (OAuth2) ###
+
+When OAuth2 is enabled on the server, `mcp-remote` handles the authorization flow automatically—it discovers the authorization server and opens a browser for consent.
+
+```json
+{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://localhost:8080/mcp", "--allow-http"]
+    }
+  }
+}
+```
+
+The `--allow-http` flag is needed for `http://` URLs (development). Omit it in production with HTTPS.
+
+See the [HTTP security model](../security/http.md) for server-side OAuth2 setup.

docs/clients/cursor.md

@@ -0,0 +1,72 @@
+# Cursor
+
+[Cursor](https://cursor.sh/) supports MCP servers natively via project configuration files or the Cursor Settings UI.
+
+***
+
+## STDIO Mode (Recommended) ##
+
+### Project Configuration (`.cursor/mcp.json`) ###
+
+Create `.cursor/mcp.json` in your project root:
+
+**JAR:**
+
+```json
+{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "java",
+      "args": ["-jar", "/absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar"],
+      "env": { "SOLR_URL": "http://localhost:8983/solr/" }
+    }
+  }
+}
+```
+
+**Docker (local image — build first with `./gradlew jibDockerBuild`):**
+
+```json
+{
+  "mcpServers": {
+    "solr-mcp": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm",
+               "-e", "SOLR_URL=http://host.docker.internal:8983/solr/",
+               "solr-mcp:latest"]
+    }
+  }
+}
+```
+
+**Linux users**: add `"--add-host=host.docker.internal:host-gateway"` to the `args` array.
+
+### Cursor Settings UI ###
+
+1. Open **Cursor Settings** (gear icon or <kbd>Cmd+,</kbd> / <kbd>Ctrl+,</kbd>)
+2. Navigate to **Features** > **MCP Servers**
+3. Click **Add New MCP Server**
+4. Enter:
+    * **Name**: `solr-mcp`
+    * **Type**: `command`
+    * **Command**: `java -jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar`
+
+***
+
+## HTTP Mode ##
+
+Start the server in HTTP mode first (`PROFILES=http java -jar build/libs/solr-mcp-1.0.0-SNAPSHOT.jar`, or `PROFILES=http ./gradlew bootRun`), then:
+
+```json
+{
+  "mcpServers": {
+    "solr-mcp": {
+      "url": "http://localhost:8080/mcp"
+    }
+  }
+}
+```
+
+The configuration is the same for secured and unsecured HTTP. Cursor handles the MCP OAuth2 flow automatically.
+
+See the [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol) for the latest configuration format.