Supports all MCP transports (stdio, sse, streamable-http, stateless-http) and both servlet (WebMVC) and reactive (WebFlux) stacks. The design follows the same pattern as springdoc-openapi-starter-webmvc-ui, zero-config when defaults work, fully overridable when they don't.
Why
Spring AI's MCP server starters give you a running MCP endpoint, but no UI to talk to it. The reference is a standalone Node app that you point at a remote server. This library embeds that same React UI directly into your Spring Boot app, so:
Bring MCP Inspector to your MCP server with one dependency
one process, one port, no separate proxy to deploy
the inspector connects loopback, so it works in air-gapped/dev environments
the bootstrap payload (proxy URL, auth token, default server, headers) is pre-filled from your Spring configuration, no copy-paste of secrets into the UI
Requirements
Java 17+
Spring Boot 4.1+
Spring AI 2.0+ (org.springframework.ai:spring-ai-bom)
Boot 3.5 / Spring AI 1.1 are served by the 1.x line, maintained on develop/1.x.
Compatibility
Each library release is built and tested against a fixed set of upstream versions.
The table below records the exact stack a given inspector release was verified with.
spring-ai-mcp-inspector
Spring Boot
Spring AI
Java MCP SDK
Bundled MCP Inspector UI
1.0.0
3.5.15
1.1.8
0.18.3
0.21.2
2.0.0
4.1.0
2.0.0
2.0.0
0.22.0
2.1.0
4.1.0
2.0.0
2.0.0
0.22.0
Upgrading from 2.0.0
Nothing to change in your code or configuration. One runtime behaviour is different:
the inspector now closes the MCP server's transport provider when the context starts
closing, instead of leaving it to bean destruction. That is what stops a graceful
shutdown from waiting out its whole timeout — and it means an MCP tool call still
streaming when shutdown begins is cut short rather than being given the full window.
Set spring.ai.mcp.inspector.shutdown.close-mcp-server-transports: false to keep the
old behaviour; see Graceful shutdown for the trade-off.
Quickstart
WebMVC
Add the starter alongside your existing spring-ai-starter-mcp-server-webmvc dependency:
Start your application and open http://localhost:8080/mcp-inspector/. The inspector is pre-connected to your local MCP server, click Connect and you'll see tools/resources/prompts immediately.
Security
The inspector is a development tool. Its built-in token is not a security boundary.
Two facts make that plain:
GET ${spring.ai.mcp.inspector.path}/config serves the bootstrap payload — including
the auth token — unauthenticated, by design. The SPA is a static bundle; it has to
fetch the token before it can call anything. Whoever can reach that URL has the token.
The proxy backend dials arbitrary absolute URLs supplied by the client. Anyone who
can reach the port can therefore make outbound requests from inside your network, to
hosts your users cannot reach directly.
So the only real control is who can reach the port. Outside a trusted network, either
turn the inspector off:
spring:
ai:
mcp:
inspector:
enabled: false
or put it behind your application's own authentication.
Behind Spring Security
McpInspectorProperties#securityPathPatterns() returns every path the inspector claims —
the UI base path, the proxy backend and the two fixed OAuth callback routes — so the rules
below keep working when you move spring.ai.mcp.inspector.path. It is a plain method, not
a configuration property.
Two things matter in these snippets:
Use .authenticated(), notpermitAll(). permitAll() on these patterns is a full
bypass of your own authentication, which is exactly what you were trying to avoid.
Exempt the same patterns from CSRF. The UI issues POSTs (connect, jsonrpc, fetch,
message, mcp), a PUT to /roots and a DELETE to end a session, none of which
carry a CSRF token — without the exemption CsrfFilter answers 403 on the very first
Connect.
Setting spring.ai.mcp.inspector.auth-enabled=false drops the built-in token check
entirely and logs a WARN at startup. Only do that when something else — Spring Security,
a network boundary — already guards the path.
Under a context path or behind a reverse proxy
A server.servlet.context-path (or spring.webflux.base-path) needs no extra
configuration: asset URLs, the root redirect, the advertised proxy address and the
detected MCP endpoint are all prefixed with it.
Behind a reverse proxy
When a gateway serves the app under a prefix that the app itself does not know about, let
Spring read the forwarded headers:
server:
forward-headers-strategy: framework
The gateway then sends X-Forwarded-Prefix and the inspector emits links under that
prefix.
One sharp edge: X-Forwarded-Prefix replaces the context path, it does not concatenate
with it. An app on context-path=/app behind a gateway that routes /tools/* to it must
receive X-Forwarded-Prefix: /tools/app — the combined prefix. Sending /tools alone
produces links that drop /app.
Known limitations under a prefix
OAuth does not work under a context path. The SPA hardcodes
window.location.origin + "/oauth/callback" as its redirect_uri and compares
window.location.pathname against that same literal, so both halves of the flow break
once the app is not mounted at the root. Fixing it requires patching the upstream
bundle; the inspector serves those two callback routes at the top level on purpose.
Its code-split callback chunks are likewise still fetched from /mcp-inspector/assets/.
The SSE transport needs one extra Spring AI property. Spring AI advertises the
message endpoint as spring.ai.mcp.server.base-url + sse-message-endpoint; left empty
(the default) it is advertised without the prefix and the first client-to-server frame
404s. Set it to the prefix:
All settings live under the spring.ai.mcp.inspector namespace:
Property
Default
Description
spring.ai.mcp.inspector.enabled
true
Toggle the inspector entirely.
spring.ai.mcp.inspector.path
/mcp-inspector
Base path the UI is served at. Must start with /, no trailing /.
spring.ai.mcp.inspector.auth-enabled
true
When true, requests to the proxy endpoint require the bearer token below.
spring.ai.mcp.inspector.auth-token
(generated)
Bearer token. If unset, a random token is generated at boot and injected into the SPA bootstrap automatically.
spring.ai.mcp.inspector.allowed-origins
(empty)
Origins allowed to call the inspector API and proxy cross-origin. Empty means no CORS mapping is registered at all, so only same-origin browser calls work — set it only when the UI is served from a different host than the app. Accepts a YAML list.
Inspector now lives at /admin/inspector/; the proxy is at /admin/inspector-api.
Proxy timeouts
The proxy backend ships with upstream-compatible defaults. Override them under
spring.ai.mcp.inspector.timeouts when an MCP server is unusually slow (or to fail
fast). All values use Spring's relaxed Duration syntax — e.g. 30s, 2m, 500ms.
Property
Default
Description
spring.ai.mcp.inspector.timeouts.sse-session
30m
Inactivity budget for a proxied SSE / streamable-HTTP browser session (servlet stack only).
On rare occasions a request through a pooled java.net.http.HttpClient connection parks
until its own timeout expires while a freshly built client answers the same request in
milliseconds. The request is not lost — it reaches the upstream server at the moment the
caller gives up, which can leave behind an upstream MCP session whose id the inspector
never learns. Observed rate on a loaded CI runner is roughly one to three stalls per two
hundred sequential requests.
Every browser-visible wait is bounded, so a stall surfaces as an error rather than a hang:
the streamable-HTTP proxy answers 504 after timeouts.streamable-request and removes
its own ProxySession: the upstream MCP server never receives the DELETE that would
close the upstream session, because the transport learns the mcp-session-id from a response
header and no response has arrived yet. The upstream session remains alive until that server's
own idle timeout. /fetch answers 502 after timeouts.fetch-request. Retrying
the operation from the UI succeeds.
The inspector does not retry on your behalf. The JDK exposes no per-client way to validate
or evict a pooled connection, and it never replays a request that failed on a timeout — for
any method. The only cure is to replay on a brand-new HttpClient, and none of the affected
requests can be replayed safely: a repeated POST /mcp re-runs the tool upstream, a repeated
initialize opens a second upstream session, and a repeated OAuth token exchange burns the
single-use authorization code.
Two levers do exist, and both belong to the application that runs the JVM — they are global
system properties read once at class-initialization time, so a starter must not set them for you:
Run JDK 17.0.21 or newer. JDK-8277969 (fixed
in 17.0.17) and JDK-8304701 (fixed in 17.0.21)
are both live in older 17.0.x and both bite the shapes this proxy uses.
-Djdk.httpclient.keepalive.timeout=30 evicts idle pooled connections before an intermediary
silently drops them. JDK 17 defaults to 1200 seconds; JDK 20 and newer already default to 30.
Graceful shutdown
Boot defaults server.shutdown to graceful, which blocks context close until every
in-flight request finishes or spring.lifecycle.timeout-per-shutdown-phase expires. A live
MCP session pins an inbound request open and never finishes on its own, so an application
with the inspector attached used to pay that timeout in full on every shutdown.
The inspector releases its own streams at the start of context close. It also closes the
host application's MCP server transport provider there, because spring-ai leaves that to
bean destruction — which happens after the graceful wait has already been paid, so the
session that caused the wait is released too late to shorten it.
Close the MCP server transport provider on ContextClosedEvent instead of at bean destruction.
The default has a cost worth knowing about. Closing the provider early terminates the
server's MCP sessions, so an MCP tool call that is still streaming its response when
shutdown begins is cut short, where today it would get the whole graceful window to
finish. For the case that actually occurs — an idle listening stream, which can never
drain by itself and only ever burns the timeout — the trade is clearly worth it, which is
why it is on. If your tools legitimately run for tens of seconds and you would rather pay
the timeout than cut them off:
The setting only exists where the inspector does: no application gets this behaviour
merely by having spring-ai on the classpath.
Customizing the inspector bootstrap
When the inspector serves index.html it injects a single inline
<script>window.__MCP_INSPECTOR_BOOTSTRAP = { ... }</script> block that the
upstream React bundle reads at boot. The same payload is exposed as JSON at
GET ${spring.ai.mcp.inspector.path}/config (default: /mcp-inspector/config).
You can pre-populate this payload from your own Spring @Configuration by
registering one or more InspectorBootstrapCustomizer beans. Each customizer
receives the freshly-assembled InspectorBootstrap instance after the framework
defaults (authToken, proxyAddress, detectedTransport, detectedUrl) have
been applied, and may mutate it in-place.
import io.inspector.mcp.core.bootstrap.CustomHeader;
import io.inspector.mcp.core.bootstrap.InspectorBootstrapCustomizer;
import io.inspector.mcp.core.bootstrap.ServerEntry;
import java.util.Map;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.annotation.Order;
@Configuration
class InspectorCustomizers {
/** Pre-fill the inspector form with a preferred MCP server URL. */
@Bean
@Order(10)
InspectorBootstrapCustomizer prefillDefaultUrl() {
return bootstrap -> bootstrap.setDefaultUrl("https://internal-mcp.acme.com/mcp");
}
/** Surface an auto-discovered MCP server in the inspector's picker. */
@Bean
@Order(20)
InspectorBootstrapCustomizer autoDiscoveredServers() {
return bootstrap -> bootstrap.getServerEntries().add(
new ServerEntry(
"internal",
"https://internal-mcp/mcp",
"streamable-http",
Map.of("X-Tenant-Id", "acme")));
}
/** Add tenant-scoped headers that every outgoing MCP request will carry. */
@Bean
@Order(30)
InspectorBootstrapCustomizer tenantHeader() {
return bootstrap -> bootstrap.getDefaultHeaders().add(
CustomHeader.of("X-Tenant-Id", "acme"));
}
}
Ordering multiple customizers
Customizers are invoked in standard Spring @Order sequence, lower values run
first, higher values run last, and on a conflict the last customizer to set
a field wins. Customizers without an explicit @Order are treated as having
Ordered.LOWEST_PRECEDENCE.
spring-ai-mcp-inspector-core # transport-agnostic core: properties, bootstrap, controllers
spring-ai-mcp-inspector-starter-webmvc # Spring Boot starter for the servlet stack
spring-ai-mcp-inspector-starter-webflux # Spring Boot starter for the reactive stack
spring-ai-mcp-inspector-ui # Vendored upstream React/Vite bundle
spring-ai-mcp-inspector-demo-app # Demo MCP server (tools/resources/prompts), no web stack
spring-ai-mcp-inspector-demo-webmvc # Demo on the servlet stack — the runnable jar
spring-ai-mcp-inspector-demo-webflux # Demo on the reactive stack
The demo is split in three so that each web stack gets a classpath of its own:
with both starters visible, Spring Boot silently runs the "reactive" setup on
Tomcat-reactive. -demo-app holds the application and the stack-agnostic tests;
the two stack modules add exactly one starter each.
Then open http://localhost:8080/mcp-inspector/. The demo registers a handful of tools that exercise sampling, elicitation, and roots — useful for kicking the tires on MCP features end-to-end.
This project bundles a fork of the official MCP Inspector React client under spring-ai-mcp-inspector-ui/upstream-client/ with a small number of patches.
S
Spring Ai MCP Inspector
a-simeshin·2 个星标·
Bring MCP Inspector to your MCP server with one dependency