Swagger MCP Bridge MCP server

Swagger MCP Bridge

Turn any SpringDoc-powered Spring Boot API into a production-ready MCP gateway.

Swagger MCP Bridge discovers your OpenAPI operations, publishes them as safe MCP tools, and adds a smart gateway layer for API discovery, validation, response shaping, and multi-step workflow orchestration.

Naming and Coordinates

This repository intentionally separates the public surfaces so each one reads naturally in its own ecosystem:

The project name keeps the established bridge branding, while the Maven artifact uses the neutral OpenAPI/Spring Boot starter coordinate expected by Java consumers. The registry server and GHCR image identify the packaged runnable example used by MCP directories.

Why Swagger MCP Bridge

Most MCP API bridges stop at a thin tool wrapper. Swagger MCP Bridge is designed as a runtime gateway: it exposes your existing Spring controllers to LLM clients while preserving contracts, guardrails, and operational visibility.

What You Get

• Zero-boilerplate discovery of SpringDoc OpenAPI operations from your running Spring app
• Automatic MCP tool registration for discovered API operations
• Smart-context gateway tools: metagetapicapabilities, metavalidateapicall, metadiscoverapitools, metadescribeapitool, metalistapigroups, metaplanapiworkflow, metainvokeapiworkflow, metainvokeapiby_intent
• API catalog and workflow layer for capability inspection, preflight validation, grouped exploration, dry-run planning, and sequential execution
• Rich MCP input schemas generated from OpenAPI constraints: required fields, enums, numeric/string/object limits, examples, and deprecation hints
• Response shaping with JSONPath projection and summarization controls
• Execution guardrails: required argument validation, unresolved path-template protection, and safe _headers filtering
• Structured MCP error responses with stable codes such as INVALIDARGUMENT, SECURITYDENIED, WORKFLOWERROR, and HTTPDISPATCH_FAILED
• Java 17 bytecode with CI coverage on Java 17, 21, and 25
• Optional virtual-thread HTTP dispatch on Java 21+ runtimes, with automatic platform-thread fallback on Java 17
• Production guardrails for dangerous operations: _confirm, blocked paths, role checks, audit logs, and structured client errors

Architecture

graph TD
    User([User / LLM Client]) <--> MCP[MCP Client / Claude Desktop]
    MCP <--> Bridge[Swagger MCP Bridge /starter/]
    Bridge --> Catalog[Operation Catalog /groups + contracts/]
    Bridge --> Workflow[Workflow Orchestrator /plan + dry-run + execute/]
    Bridge <--> Docs[SpringDoc OpenAPI /v3/api-docs]
    Bridge <--> API[Your Spring Controller /hello]

Quick Start

1. Create a Spring Boot app

Use:

• Java 17+
• Spring Boot 3.5.x
• Spring Web

2. Add dependencies

Gradle (build.gradle.kts):

Shortened. The full README is on GitHub.