Spring Boot Starter Swagger MCP

What Neo1228/spring-boot-starter-swagger-mcp MCP server does

Neo1228/spring-boot-starter-swagger-mcp MCP server exposes operations from a SpringDoc-powered Spring Boot API through MCP. It discovers the application's OpenAPI document and creates MCP tools from the documented operations, using operation identifiers and a configurable name prefix. Existing controller annotations and OpenAPI constraints supply the generated input schemas.

Alongside direct API tools, the bridge provides a gateway layer for inspecting and using larger APIs. Clients can list API groups, search for operations from a natural-language request, inspect a selected tool, validate a call without sending an HTTP request, plan a multi-step workflow, and execute workflow steps sequentially.

How it works

The starter runs inside the Spring Boot application. It reads OpenAPI data from the configured API-docs path, which defaults to the SpringDoc endpoint shown in the quick-start configuration. The MCP server uses Spring AI MCP server settings; the example configures Streamable HTTP with /mcp as the MCP endpoint.

Generated tool names use the configured tool-name-prefix followed by the operation ID. The gateway also applies that prefix to its metadata and workflow tools. Input schemas can include required parameters, enums, numeric and string limits, object constraints, examples, and deprecation information derived from OpenAPI.

Calls can be shaped with JSONPath projection and summarization controls. Validation checks required arguments, unresolved path templates, and other dispatch conditions before an API request is sent. Risk controls include confirmation requirements, blocked paths, role checks, audit logs, and filtering for the special _headers argument. Rejections return readable text and structured errors with codes such as INVALID_ARGUMENT, SECURITY_DENIED, WORKFLOW_ERROR, and HTTP_DISPATCH_FAILED.

Setup and configuration

To add the Neo1228/spring-boot-starter-swagger-mcp MCP server, use Java 17 or newer, Spring Boot 3.5.x, Spring Web, and SpringDoc's WebMVC API starter. The Maven artifact is io.github.neo1228:openapi-mcp-spring-boot-starter; the README also provides Gradle and Maven dependency examples.

Enable the bridge with the swagger.mcp.* configuration prefix. The documented settings include swagger.mcp.enabled, swagger.mcp.api-docs-path, and swagger.mcp.tool-name-prefix. Configure the Spring AI MCP server protocol as STREAMABLE_HTTP and set its endpoint, such as /mcp.

After starting the application with Gradle or Maven, check the OpenAPI document at /v3/api-docs, check the MCP endpoint at /mcp, and connect an MCP client. The example uses a HelloController with a documented GET /hello operation, which becomes a generated MCP tool.

Tools and capabilities

The gateway tools documented by the project are:

• meta_get_api_capabilities
• meta_list_api_groups
• meta_discover_api_tools
• meta_describe_api_tool
• meta_validate_api_call
• meta_plan_api_workflow
• meta_invoke_api_workflow
• meta_invoke_api_by_intent

A recommended client flow is to inspect capabilities, discover or group operations, describe the selected tool, validate the call, and use dry-run planning before executing a multi-step workflow.

Limitations and notes

The Neo1228/spring-boot-starter-swagger-mcp MCP server depends on an existing SpringDoc OpenAPI description and Spring Boot application; it is not presented as a standalone API connector. The documented compatibility targets are Java 17 or newer and Spring Boot 3.5.x. Virtual-thread HTTP dispatch is optional on Java 21 or newer, with platform-thread fallback on Java 17.

The README identifies Claude Desktop as an MCP client in its architecture and workflow examples, but does not provide client-specific configuration for other clients. The project uses Apache License 2.0. The provided material does not specify authentication settings or environment variables.