Creating a human readable MCP error page. #5767

nielsbasjes · 2026-04-07T15:30:45Z

nielsbasjes
Apr 7, 2026

FYI: I'm currently trying out a local build of the 2.0.0-SNAPSHOT code base.

I wrote my first McpTool to learn how this all works.
One of the things I noticed is that when a user opens the /mcp path I usually get an HTTP 405 without any explanation.

In an attempt to show a human readable error message I simply added a GetMapping linked to the content type HTML like this:

    @GetMapping(value = "/mcp", produces = MediaType.TEXT_HTML_VALUE)
    public String showMcpInstructions() {

I would expect that this would be shown when a normal browser opens this url, but it doesn't. I still get the 405 error.

After digging through the code I found that in the Spring AI code a RouterFunction is used that simply returns the 405 on all GET operations on the /mcp.

So to override that I wrote this (code summary only):

    @Bean
    @Order(HIGHEST_PRECEDENCE)
    public RouterFunction<?> mcpHumanHelperPage() {
        return RouterFunctions.route()
            .GET("/mcp", RequestPredicates.accept(MediaType.TEXT_HTML), (serverRequest) ->
                ServerResponse
                    .status(HttpStatus.METHOD_NOT_ALLOWED)
                    .contentType(MediaType.TEXT_HTML)
                    .body("""
                        <!DOCTYPE html>
...
                        """))
            .build();
    }

My main question is if this is really the way to do this?
Or is there a simpler and cleaner way I'm simply not aware of yet?

Also: Why such a hard coded error?

I also noticed that those RouterFunction calls all do a very broad GET/POST/DELETE and then in the handler check for the actually accepted content type. I think this is a better alternative:

this.routerFunction = RouterFunctions.route()
    .POST(
        this.mcpEndpoint, 
        RequestPredicates.accept(MediaType.TEXT_EVENT_STREAM, MediaType.APPLICATION_JSON),
        this::handlePost)
    .build();

nielsbasjes · 2026-04-07T16:25:23Z

nielsbasjes
Apr 7, 2026
Author

I propose this fix for this: #5769

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Creating a human readable MCP error page. #5767

Uh oh!

{{title}}

Uh oh!

Replies: 1 comment

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Creating a human readable MCP error page. #5767

Uh oh!

nielsbasjes Apr 7, 2026

Replies: 1 comment

Uh oh!

nielsbasjes Apr 7, 2026 Author

nielsbasjes
Apr 7, 2026

nielsbasjes
Apr 7, 2026
Author