api2mcp4j MCP server
Commit Oct 28, 2026Auto-converts existing Spring Boot REST controllers into MCP tools without code changes using a zero-config starter.
Also known as TheEterna/api2mcp4j
- Stars
- 114
- Tools
- β
- Downloads, 30 days
- β
- Latest version
- β
- Last commit
- Oct 28, 2026
- License
- Apache-2.0
What is api2mcp4j MCP?
api2mcp4j is an MCP server. Auto-converts existing Spring Boot REST controllers into MCP tools without code changes using a zero-config starter.
Summary generated from the project's README
About api2mcp4j MCP server
Java developers can transform existing Spring Boot REST controllers into Model Context Protocol tools without modifying their original business logic. By adding a specific dependency to a project, the framework automatically scans @RestController beans and exposes their methods as MCP tools. This approach eliminates the need to manually add annotations like @Tool to every method or duplicate logic into separate code paths.
The system supports both standard Spring MVC and reactive Spring WebFlux applications through dedicated starters. It utilizes a five-parser chain that extracts tool descriptions from Swagger v3, Swagger v2, Javadoc, Spring MVC, Jackson, or Spring AI to ensure the best possible metadata is provided to AI clients. The server is accessible locally via JSON-RPC endpoints and supports SSE for notifications.
This implementation provides full compatibility with the 2026-07-28 protocol version, offering advanced features like task management, augmented prompts, and MRTR state machines. It is designed for integration with clients such as Claude Desktop, Cursor, or Cline, providing a bridge between enterprise Java services and AI agents.
What you can do with it
- 1Expose REST APIs to AIConvert your existing Spring Boot controllers into MCP tools without writing any new code.
- 2Automate tool descriptionsGenerate high-quality tool metadata by pulling information from Swagger or Javadoc automatically.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report βNot verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work Β· What to fix for more points
- Source repository linked and reachabletheeterna/api2mcp4j is public and reachablegithub.com/theeterna/api2mcp4j βPass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html βPass
- Commit or release in the last yearLast commit or release 2026-10-28github.com/theeterna/api2mcp4j βPass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubapi2mcp4j
Turn your existing Spring Boot REST controllers into MCP (Model Context Protocol) tools β no rewrites, no @Tool everywhere.
<dependency>
<groupId>io.github.theeterna</groupId>
<artifactId>server2mcp-starter-webmvc</artifactId>
<version>1.2.0</version>
</dependency>
English Β· δΈζ Β· Docs Β· Integration Matrix
Why api2mcp4j?
Most MCP integrations force you to:
- Add
@Tool/@McpToolto every method - Duplicate business logic into a parallel "MCP" code path
- Maintain separate tool descriptions
api2mcp4j scans your existing @RestController beans and exposes their methods as MCP tools β zero changes to business code. Like MyBatis-Plus enhances MyBatis, api2mcp4j enhances Spring AI MCP.
// Your existing controller β unchanged
@RestController
public class OrderController {
@GetMapping("/orders/{id}")
public Order getOrder(@PathVariable Long id) { ... }
}
// Becomes an MCP tool: OrderController_getOrder
// With auto-generated description from Swagger / Javadoc / Spring MVC / Jackson / Spring AI
β¨ Key Features
| π― Non-intrusive | interface scope auto-registers all controllers; no @Tool annotation needed |
| π 5-parser chain | Swagger v3 / Swagger v2 / Javadoc / Spring MVC / Jackson / Spring AI β best description wins |
| π οΈ Full MCP coverage | Tools / Resources / Prompts / Completions / Elicitation / Sampling / Roots |
| π Protocol 2026-07-28 | Wire schema + JSON-RPC routing + SSE long-poll + MRTR + OTel traceparent β 100% |
| π Custom parsers | Implement AbstractDesParser / AbstractParamParser, plug into the chain |
| π§ͺ TDD discipline | JUnit5, double commit [RED] then [GREEN], 600 tests all green |
| π Quick start | mvn spring-boot:run β MCP endpoint ready |
π Quick Start (β 3 minutes)
1. Clone & build
git clone https://github.com/TheEterna/api2mcp4j.git
cd api2mcp4j
mvn clean install -DskipTests
2. Add to your Spring Boot project
<dependency>
<groupId>io.github.theeterna</groupId>
<artifactId>server2mcp-starter-webmvc</artifactId>
<version>1.2.0</version>
</dependency>
Reactive (Spring WebFlux) applications use the WebFlux starter instead β identical protocol surface, reactive transport:
<dependency>
<groupId>io.github.theeterna</groupId>
<artifactId>server2mcp-starter-webflux</artifactId>
<version>1.2.0</version>
</dependency>
3. Configure
plugin:
mcp:
enabled: true
scope: interface # 'interface' = auto-register all controllers; 'custom' = @ToolScan only
parser:
des: MCPTOOL, JAVADOC, TOOL, JACKSON, SWAGGER3, SWAGGER2
param: MCPTOOL, JAVADOC, TOOL, SpringMVC, JACKSON, SWAGGER2, SWAGGER3
strict: false # true = a misspelled parser name aborts startup (default: warn only)
4. Start & test
mvn spring-boot:run
Your MCP server is live on http://localhost:8080/mcp/jsonrpc (and HTTP fallbacks on /mcp/discover, /mcp/tasks, /mcp/sse).
π‘ MCP Protocol 2026-07-28 β 100% Compatible
api2mcp4j is the first Java MCP framework to ship full 2026-07-28 support, even though Java MCP SDK 2.0 only implements the 2025-11-25 wire. We bypassed SDK limitations with a custom JSON-RPC router, SSE controller, and wire schema β all without breaking SDK upgrade compatibility (controllers stay as fallbacks when SDK β₯ 3.0.0 lands).
8 RPC routes, all real (not HTTP simulations)
| RPC | JSON-RPC endpoint | SSE long-poll | Source |
|---|---|---|---|
server/discover |
β
POST /mcp/jsonrpc |
β | DiscoverEndpoint |
tasks/create |
β | β | TaskStore |
tasks/get / list / cancel |
β | β | TasksEndpoint |
tasks/augmented-prompt |
β | β | AugmentedPromptEndpoint |
subscriptions/listen |
β (poll) | β
GET /mcp/sse + Last-Event-ID + 15s heartbeat |
SseNotificationsController |
input_required/respond (MRTR) |
β envelope | β | MrtrToolCallbackWrapper |
Wire JSON fields β 100% reachable
| 2026-07-28 field | Status | Where |
|---|---|---|
tools.listChanged / resources.listChanged / prompts.listChanged |
β SDK native | WireSchemaExporter.syncAll() |
tools.subscription / completions.listChanged (new in 2026-07-28) |
β Custom wire | WireServerCapabilities |
experimental.io.modelcontextprotocol/tasks (new) |
β Custom wire | Same |
_meta.resultType / ttlMs / cacheScope / cacheWrapperKey |
β Auto-injected via meta map | @McpTool(...) + McpCallToolResultConverter |
_meta.taskHandle / inputRequests / requestState |
β Auto-recognized | InputRequiredResult / TaskHandle return values |
_meta.traceparent / tracestate / baggage (W3C SEP-414) |
β Auto-minted in JSON-RPC | MetaUtils |
| MRTR state machine (cross-round merge + 8-round guard) | β | MrtrDriver |
outputSchema |
β SDK field | McpSchema.Tool.builder().outputSchema() |
| Capabilities health / diff / wire validation | β | CapabilitiesHealth + SnapshotCompareTool + WireSchemaValidator |
β One-line verification
The demo app boots with H2 in-memory DB (zero external dependencies) and validates every 2026-07-28 feature against a real HTTP/SSE wire:
cd server2mcp-test && mvn spring-boot:run # starts on :8888 (H2 in-memory)
# In another shell:
bash scripts/verify-protocol-2026-07-28.sh http://localhost:8888
== 0. liveness == β actuator reachable
== 1. server/discover (JSON-RPC) == βΓ7 (jsonrpc=2.0, preferredVersion=2026-07-28,
tools.listChanged, tools.subscription,
completions.listChanged, experimental.tasks,
_meta.traceparent)
== 2. tasks/* (JSON-RPC) == βΓ5 (create, get, list, cancel full lifecycle)
== 3. tasks/augmented-prompt == βΓ1
== 4. subscriptions/listen == βΓ3 (HTTP poll + text/event-stream + connected)
== 5. input_required/respond == βΓ2 (accepted + state echo)
== 6. HTTP legacy endpoints == βΓ2 (/mcp/discover + /mcp/notifications)
== summary == passed: 21 / failed: 0
ALL ASSERTIONS PASSED β protocol 2026-07-28 wire verified
π§ͺ Testing & Verification
| Layer | Count | Status |
|---|---|---|
Unit tests (server2mcp-core) |
575 | β all green |
Integration tests (server2mcp-starter-webmvc) |
22 | β all green |
Demo tests (server2mcp-test) |
3 | β all green |
| End-to-end curl verification | 21/21 | β |
| Total | 600+ tests, 21/21 e2e | β |
Test philosophy: TDD double-commit β [RED] test first, then [GREEN] implementation. See docs/specs/TEST_SPEC.md.
ποΈ Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Spring Boot Application β
β β
β ββββ Your existing code (unchanged) ββββ β
β β @RestController β β
β β @Service β β
β β @Component β β
β ββββββββββββββββββ¬ββββββββββββββββββββββ β
β β β
β ββββββββββββββββββΌββββββββββββββββββββββ β
β β api2mcp4j framework β β
β β β β
β β Scanner βββ Parser chain βββ Provider β
β β β β β β
β β Spring MVC 5 parsers SyncMcpToolMethodCallback β
β β discovery (Swagger2/3, (template method) β
β β Javadoc, β
β β Jackson, β
β β Spring AI) β
β β β β
β β ββ 2026-07-28 layer (new) ββ β
β β β’ JsonRpcRouter + JsonRpcRoutes β
β β β’ WireServerCapabilities + JsonExporter β
β β β’ SseNotificationsController β
β β β’ MrtrDriver + MrtrSessionStore β
β β β’ MrtrToolCallbackWrapper β
β β β’ MetaUtils (W3C traceparent mint) β
β ββββββββββββββββββ¬ββββββββββββββββββββββ β
β β β
β ββββββββββββββββββΌββββββββββββββββββββββ β
β β Spring AI MCP SDK 2.0 β β
β β (McpSyncServer / McpAsyncServer) β β
β ββββββββββββββββββ¬ββββββββββββββββββββββ β
ββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββ
β wire: JSON-RPC 2.0 + SSE
βΌ
ββββββββββββββββββββββ
β MCP Clients β
β β’ Claude Desktop β
β β’ Cursor / Cline β
β β’ Your BFF / Agent β
ββββββββββββββββββββββ
π¦ Modules
api2mcp4j/
βββ server2mcp-common # Constants & utilities
βββ server2mcp-core # Core engine: annotations, scanners, callbacks, providers
β βββ com.ai.plug.core.annotation.* # @McpTool, @McpResource, @McpPrompt, @McpArg
β βββ com.ai.plug.core.parser.* # 5-parser chain (des + param)
β βββ com.ai.plug.core.callback.* # Sync + Async template methods
β βββ com.ai.plug.core.spec.* # 2026-07-28 wire layer
β βββ com.ai.plug.core.provider.* # Spring AI bridge
βββ server2mcp-autoconfigure # Spring Boot auto-configuration
βββ server2mcp-spring-boot-starters/
β βββ server2mcp-starter-webmvc # β
Full endpoint wiring (JSON-RPC + SSE + HTTP)
β βββ server2mcp-starter-webflux # β
Reactive endpoint wiring β full protocol parity with WebMVC
βββ server2mcp-test # β
Demo app + 21/21 e2e verification
π€ When to use api2mcp4j?
| β Use it for | β Don't use it for |
|---|---|
| Exposing internal REST APIs to AI agents quickly | Greenfield MCP-first projects (use Spring AI MCP directly) |
| Wrapping legacy controllers as MCP tools | Real-time streaming / SSE-only UIs |
| Multi-agent systems sharing tool definitions | Apps that don't already use Spring Boot |
| Prototyping AI features on production services | Tiny prototypes (overhead not worth it) |
π Comparison
| Feature | api2mcp4j | Spring AI MCP Official | Manual @Tool everywhere |
|---|---|---|---|
| Code changes required | Minimal (config only) | MediumβHigh | High |
Auto-discover from @RestController |
β | β | β |
| 5-parser chain (Swagger + Javadoc + β¦) | β | Limited | Manual |
| Non-intrusive | β β β β β | β β β | β β |
| Protocol 2026-07-28 (RPC + wire) | β 100% | π‘ partial | βͺ |
| MRTR multi-round | β with decorator | βͺ | βͺ |
| SSE long-poll + Last-Event-ID | β built-in | π‘ via SDK | β |
| W3C traceparent (SEP-414) | β auto-minted | β | β |
| Best for existing projects | β | New apps | Tiny demos |
π Documentation
- π Full docs site β https://theeterna.github.io/server2mcp-docs/
- π Protocol 2026-07-28 integration matrix β docs/mcp-2026-07-28-INTEGRATION-MATRIX.md
- ποΈ Architecture β docs/reference/architecture.md
- π§© Extension points (custom parsers / filters / context) β docs/reference/extension-points.md
- πΆ Onboarding (3-step) β docs/reference/onboarding.md
- π Specs (registration / file header / test / work log) β docs/specs/
- βοΈ Global rules β docs/rules/
- π Work logs (audit trail) β docs/logs/
π€ Contributing
Issues, PRs, and β are very welcome.
This is a young project β your feedback shapes its future.
Before submitting a PR, please read:
- docs/specs/REGISTRATION_DISCIPLINE_SPEC.md β the 6-dimension Rubric for new MCP entities
- docs/rules/global/destructive-deletion.md β multi-source verification before deleting public APIs
- docs/rules/global/work-log.md β reportable outputs land in
docs/logs/
π License
ποΈ Roadmap
- Protocol 2026-07-28 wire & JSON-RPC routing (2026-08-03)
- MRTR multi-round state machine + 8-round guard
- SSE long-poll with Last-Event-ID resume
- W3C traceparent auto-mint
- WebFlux starter endpoint wiring (parity with WebMVC) (2026-10-27)
- Publish to Maven Central β artifacts built, signed, and audited; awaiting Central Portal credentials
- OTel SDK real instrumentation (currently wire-format only)
- Multi-tenant isolation (
@McpTool(tenant = "...")) - SDK β₯ 3.0.0 native router migration (tracked by
scripts/trigger-phase3.sh)
api2mcp4j MCP questions
How do I expose my Spring Boot REST controllers as MCP tools?
Add the server2mcp-starter-webmvc dependency, enable the plugin with scope set to interface, and your @RestController beans are auto-registered as MCP tools.
Does api2mcp4j require @Tool annotations on my methods?
No. In interface scope all controllers are auto-registered and no @Tool annotation is needed.
Which MCP protocol version does api2mcp4j support?
It supports protocol 2026-07-28 with full coverage of tools, resources, prompts, tasks, subscriptions, and MRTR.
Does api2mcp4j work with WebFlux reactive applications?
Yes, use the server2mcp-starter-webflux artifact instead of the WebMVC starter for the same protocol surface.