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 MCP Inspector 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:
- 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.
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:
<dependency>
<groupId>io.github.a-simeshin</groupId>
<artifactId>spring-ai-mcp-inspector-starter-webmvc</artifactId>
<version>2.1.0</version>
</dependency>
WebFlux
<dependency>
<groupId>io.github.a-simeshin</groupId>
<artifactId>spring-ai-mcp-inspector-starter-webflux</artifactId>
<version>2.1.0</version>
</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}/configserves 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), aPUTto/rootsand aDELETEto end a session, none of which carry a CSRF token — without the exemptionCsrfFilteranswers403on the very first Connect.
WebMVC
@Bean
SecurityFilterChain inspectorSecurity(HttpSecurity http, McpInspectorProperties inspector) throws Exception {
String[] patterns = inspector.securityPathPatterns().toArray(String[]::new);
return http.securityMatcher(patterns)
.authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
.csrf(csrf -> csrf.ignoringRequestMatchers(patterns))
.httpBasic(Customizer.withDefaults())
.build();
}
WebFlux
@Bean
SecurityWebFilterChain inspectorSecurity(ServerHttpSecurity http, McpInspectorProperties inspector) {
String[] patterns = inspector.securityPathPatterns().toArray(String[]::new);
ServerWebExchangeMatcher matcher = ServerWebExchangeMatchers.pathMatchers(patterns);
return http.securityMatcher(matcher)
.authorizeExchange(auth -> auth.anyExchange().authenticated())
.csrf(csrf -> csrf.requireCsrfProtectionMatcher(
new NegatedServerWebExchangeMatcher(matcher)))
.httpBasic(Customizer.withDefaults())
.build();
}
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 itsredirect_uriand compareswindow.location.pathnameagainst 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:server: servlet: context-path: /app spring: ai: mcp: server: base-url: /appSTREAMABLEneeds nothing extra.
Ported 95% of original MCP Inspector
Transport

Authorization and custom headers

Connection configurations

Resources

Prompts

Tools (basic)

Tools (sampling - call to LLM)

Tools (elicitation - call to User)

Roots

Tool cals and events logs

Configuration properties
All settings live under the spring.ai.mcp.inspector namespace:
Custom path example:
spring:
ai:
mcp:
inspector:
path: /admin/inspector
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.
spring:
ai:
mcp:
inspector:
timeouts:
streamable-request: 60s
server-request: 5m
Upstream connection stalls
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=30evicts idle pooled connections before an intermediary silently drops them. JDK 17 defaults to1200seconds; JDK 20 and newer already default to30.
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.
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:
spring:
ai:
mcp:
inspector:
shutdown:
close-mcp-server-transports: false
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.
@Bean @Order(10) InspectorBootstrapCustomizer a() {
return b -> b.setDefaultUrl("https://first.example/mcp"); // overwritten
}
@Bean @Order(20) InspectorBootstrapCustomizer b() {
return b -> b.setDefaultUrl("https://second.example/mcp"); // wins
}
Fields available for modification
InspectorBootstrap exposes mutable getters/setters for the full SPA boot
state:
authToken, proxy auth token (populated by the framework; rarely overridden)proxyAddress, base URL the SPA uses for proxied MCP calls (populated by the framework from the configured inspector path)detectedTransport, transport auto-detected from the running MCP serverdetectedUrl, URL of the loopback MCP serverdefaultUrl, initial value for the inspector form's MCP-server URL fielddefaultTransport, initial transport selectiondefaultHeaders,List<CustomHeader>of headers the UI ships with every outgoing request by defaultserverEntries,List<ServerEntry>shown in the server pickerextra, escape-hatchMap<String, Object>for fields not modeled as first-class properties; serialized verbatim into the JSON payload
See the javadoc on
InspectorBootstrapCustomizer
for the full contract (idempotency, latency expectations, invocation timing)
and
InspectorBootstrap
for the complete field reference.
Module layout
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.
Running the demo
./mvnw -pl spring-ai-mcp-inspector-demo-webmvc -am package -DskipTests
java -jar spring-ai-mcp-inspector-demo-webmvc/target/spring-ai-mcp-inspector-demo-webmvc-*-exec.jar \
--spring.profiles.active=streamable
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.
Contributing
See CONTRIBUTING.md. All participants are expected to follow the Code of Conduct.
License
Apache License 2.0 see LICENSE.
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.