This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr-mcp.git
The following commit(s) were added to refs/heads/main by this push:
new 58742fd5 docs: refresh MCP Inspector screenshots and guide for
Inspector v2 (#253)
58742fd5 is described below
commit 58742fd5217bb31d7145ca443449b5e285bd2f59
Author: Aditya Parikh <[email protected]>
AuthorDate: Mon Oct 26 15:42:48 2026 -0400
docs: refresh MCP Inspector screenshots and guide for Inspector v2 (#253)
* docs: refresh MCP Inspector screenshots and show them in the README
The screenshots in images/ predate the kebab-case tool rename and the
Inspector v2 UI, and none were referenced since the README was slimmed
in #151. Retake the six Inspector shots against the current server
(Inspector v2.9.0, films sample data, the repo's Keycloak realm), add
one showing where the bearer token goes, and embed them in a new
Screenshots section of the README.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
Signed-off-by: Aditya Parikh <[email protected]>
* docs(clients): update the MCP Inspector guide for Inspector v2
Inspector v2 replaced the transport dropdown and Connect button with a
server list: servers are added through Add Servers -> + Add manually and
connected with a toggle. Rewrite the STDIO and HTTP steps for that flow.
The OAuth2 section described the interactive OAuth flow, which never
starts against this server because /mcp is never challenged with 401.
Document the path that works instead: a bearer token sent as a custom
Authorization header, with a client_credentials example against the
Keycloak realm compose.yaml imports. Embed the refreshed screenshots.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
Signed-off-by: Aditya Parikh <[email protected]>
* docs: retake the Inspector screenshots so each shows what its caption says
The first set had a half-scrolled card and unrelated servers in the
STDIO shot, an HTTP shot that showed neither the URL nor the transport
and was taken with a token while captioned as anonymous, and no shot of
prompts. Retake them in an Inspector holding only the two Solr servers:
- STDIO: the java -jar entry connected, with the list exchange in the
protocol log.
- HTTP: the URL connected anonymously; tools list but calls need a token.
- OAuth2: the header dialog, then check-health on films succeeding.
- Prompts: search-collection completing its collection argument (new).
Match the README and guide captions to the new shots, use the
solr-mcp-stdio server ID the screenshot shows, mention the Reconnect
now notice, and describe what a too-old java looks like on the card.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
Signed-off-by: Aditya Parikh <[email protected]>
---------
Signed-off-by: Aditya Parikh <[email protected]>
Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
---
README.md | 43 +++++++++++++++
docs/clients/mcp-inspector.md | 79 ++++++++++++++++++++++++---
images/mcp-inspector-http-oauth-failure.png | Bin 123612 -> 107385 bytes
images/mcp-inspector-http-oauth-headers.png | Bin 0 -> 140518 bytes
images/mcp-inspector-http-oauth-success.png | Bin 141123 -> 114156 bytes
images/mcp-inspector-http.png | Bin 140994 -> 102038 bytes
images/mcp-inspector-list-resources.png | Bin 140711 -> 71703 bytes
images/mcp-inspector-prompt-completion.png | Bin 0 -> 110164 bytes
images/mcp-inspector-resource-completion.png | Bin 111983 -> 73645 bytes
images/mcp-inspector-stdio.png | Bin 231878 -> 103293 bytes
10 files changed, 115 insertions(+), 7 deletions(-)
diff --git a/README.md b/README.md
index c199e4be..ac1d7a66 100644
--- a/README.md
+++ b/README.md
@@ -145,6 +145,49 @@ The server implements MCP argument autocompletion, so
clients can suggest valid
Suggestions are matched case-insensitively by prefix and capped per request.
+## Screenshots
+
+**Claude Desktop (STDIO)** — answering a question about the `films` collection
with the server's tools:
+
+
+
+<details>
+<summary><b>MCP Inspector</b> — STDIO, HTTP, OAuth2, resources, prompts and
completions</summary>
+
+**STDIO** — the Inspector launches the server with `java -jar`; the protocol
log shows the tool, prompt and resource lists coming back:
+
+
+
+**HTTP** — connected over Streamable HTTP at `http://localhost:8080/mcp`.
Without a token the client connects and lists tools; calling them needs a
bearer token:
+
+
+
+**HTTP with OAuth2** — the bearer token goes in the server's **Settings →
Custom Headers**:
+
+
+
+With a valid token, tool calls succeed — here `check-health` on `films`:
+
+
+
+Without one, every tool call returns `Access Denied`:
+
+
+
+**Resources** — reading `solr://collections`:
+
+
+
+**Completions** — the `{collection}` argument of `solr://{collection}/schema`
completes to live collection names:
+
+
+
+**Prompts** — the `collection` argument of `search-collection` completes the
same way:
+
+
+
+</details>
+
## Configuration
The server reads configuration from environment variables. The essentials:
diff --git a/docs/clients/mcp-inspector.md b/docs/clients/mcp-inspector.md
index dda4fca9..ba12cbd7 100644
--- a/docs/clients/mcp-inspector.md
+++ b/docs/clients/mcp-inspector.md
@@ -2,22 +2,39 @@
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a
web-based tool for testing and debugging MCP servers. It lets you browse
available tools, invoke them interactively, and inspect responses.
+These steps are for Inspector v2 (checked against v2.9.0). The older 0.x
releases have a different layout.
+
### Install ###
```bash
npx @modelcontextprotocol/inspector
```
-This starts the Inspector UI at `http://localhost:6274`.
+This starts the Inspector UI at `http://localhost:6274` and opens it in your
browser. The terminal prints the URL with its session token
(`?MCP_INSPECTOR_API_TOKEN=…`); open that URL if no browser window appears.
+
+Servers are added from the **Servers** page with **Add Servers → + Add
manually**, and saved to `~/.mcp-inspector/mcp.json`. Connect a server with the
toggle on its card; the **Tools**, **Prompts** and **Resources** tabs then work
against it.
***
## STDIO Mode ##
-1. In MCP Inspector, select **STDIO** transport
-2. **Command**: `java`
-3. **Arguments**: `-jar /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar`
-4. Click **Connect**
+1. **Add Servers → + Add manually**
+2. **Server ID**: `solr-mcp-stdio`
+3. **Transport**: `stdio (local process)`
+4. **Command**: `java`
+5. **Arguments** (one per line):
+
+ -jar
+ /absolute/path/to/solr-mcp-1.0.0-SNAPSHOT.jar
+
+6. **Environment**: `SOLR_URL=http://localhost:8983/solr/`
+7. Click **Add**, then switch the server's toggle on
+
+The Inspector runs `java` from the `PATH` of the shell you started it in, and
the server needs Java 25. If that `java` is older, the card shows **Failed**
and the console on the right shows an `UnsupportedClassVersionError`; put the
full path to a Java 25 `java` in **Command**.
+
+Once connected, the protocol log on the right shows the `initialize`,
`tools/list`, `prompts/list` and `resources/list` exchange:
+
+
***
@@ -42,11 +59,18 @@ This starts the Inspector UI at `http://localhost:6274`.
The HTTP transport is secured by default: without a bearer token the
client still connects and lists the tools, but every tool call returns `Access
Denied`. The server never answers `/mcp` with `401`, so no OAuth login starts.
For a local experiment on your own machine only, add
`HTTP_SECURITY_ENABLED=false` to the server's environment; see the [HTTP
security model](../security/http.md) before exposing it to anyone else.
-2. In MCP Inspector, enter: `http://localhost:8080/mcp`
-3. Click **Connect**
+2. **Add Servers → + Add manually**
+3. **Server ID**: `solr-mcp-http`
+4. **Transport**: `streamable-http`
+5. **URL**: `http://localhost:8080/mcp`
+6. Click **Add**, then switch the server's toggle on
**Linux users** (Docker option): add
`--add-host=host.docker.internal:host-gateway` to the `docker run` command.
+Without a token the Inspector still connects and lists the tools; calling them
needs a bearer token (next section).
+
+
+
***
## Secured HTTP (bearer token) ##
@@ -65,4 +89,45 @@ npx @modelcontextprotocol/inspector --cli
http://localhost:8080/mcp --transport
The token's `aud` claim must contain the exact URL given here
(`http://localhost:8080/mcp`), and when it expires calls fail with `401` until
you relaunch with a fresh one.
+In the Inspector UI instead of the command line:
+
+1. Get an access token from your provider. With the Keycloak realm that
`compose.yaml` imports (start it with `docker compose --profile http up -d
keycloak`, and run the server with
`OAUTH2_ISSUER_URI=http://localhost:8180/realms/solr-mcp`):
+
+ curl -s -X POST
http://localhost:8180/realms/solr-mcp/protocol/openid-connect/token \
+ -d grant_type=client_credentials \
+ -d client_id=solr-mcp-service \
+ -d client_secret=dev-only-not-a-secret | jq -r .access_token
+
+2. On the server's card, open **Settings → Custom Headers → + Add Header**
+3. Set the key to `Authorization` and the value to `Bearer <token>`
+4. Close the dialog and click **Reconnect now** on the notice that appears (or
switch the server's toggle off and on); headers take effect on the next connect
+
+The token's audience must match the URL the Inspector connects to, so use
`http://localhost:8080/mcp` rather than `127.0.0.1` with the Keycloak realm
above.
+
+
+
+With a valid token, tool calls succeed — here `check-health` on `films`:
+
+
+
+Without one, every tool call returns `Access Denied`:
+
+
+
See the [HTTP security model](../security/http.md) for server-side OAuth2
setup with [Auth0](../security/auth0.md) and
[Keycloak](../security/keycloak.md).
+
+***
+
+## Resources, prompts and completions ##
+
+The **Resources** tab lists `solr://collections` and the
`solr://{collection}/schema` template:
+
+
+
+Typing into the template's `collection` field asks the server for completions,
which come back as live collection names:
+
+
+
+The **Prompts** tab lists the server's six workflow prompts. The `collection`
argument of `search-collection` (shown here), `index-data`, `view-schema` and
`design-schema` completes the same way:
+
+
diff --git a/images/mcp-inspector-http-oauth-failure.png
b/images/mcp-inspector-http-oauth-failure.png
index f6d188cd..58b382e3 100644
Binary files a/images/mcp-inspector-http-oauth-failure.png and
b/images/mcp-inspector-http-oauth-failure.png differ
diff --git a/images/mcp-inspector-http-oauth-headers.png
b/images/mcp-inspector-http-oauth-headers.png
new file mode 100644
index 00000000..269747a4
Binary files /dev/null and b/images/mcp-inspector-http-oauth-headers.png differ
diff --git a/images/mcp-inspector-http-oauth-success.png
b/images/mcp-inspector-http-oauth-success.png
index 9682464c..33a7ba9c 100644
Binary files a/images/mcp-inspector-http-oauth-success.png and
b/images/mcp-inspector-http-oauth-success.png differ
diff --git a/images/mcp-inspector-http.png b/images/mcp-inspector-http.png
index df01ac8f..96c7be0b 100644
Binary files a/images/mcp-inspector-http.png and
b/images/mcp-inspector-http.png differ
diff --git a/images/mcp-inspector-list-resources.png
b/images/mcp-inspector-list-resources.png
index 0507164b..77f8c298 100644
Binary files a/images/mcp-inspector-list-resources.png and
b/images/mcp-inspector-list-resources.png differ
diff --git a/images/mcp-inspector-prompt-completion.png
b/images/mcp-inspector-prompt-completion.png
new file mode 100644
index 00000000..93369934
Binary files /dev/null and b/images/mcp-inspector-prompt-completion.png differ
diff --git a/images/mcp-inspector-resource-completion.png
b/images/mcp-inspector-resource-completion.png
index 6ac2d544..913b4b62 100644
Binary files a/images/mcp-inspector-resource-completion.png and
b/images/mcp-inspector-resource-completion.png differ
diff --git a/images/mcp-inspector-stdio.png b/images/mcp-inspector-stdio.png
index cc5fd8c7..5def02af 100644
Binary files a/images/mcp-inspector-stdio.png and
b/images/mcp-inspector-stdio.png differ
