ApiHug MCP Support

Support for enterprise-level MCP, leveraging existing infrastructure and authorization protection.

Since SDK version 1.4.0-RELEASE and IDEA plugin 0.7.5, support for generating initial project templates is available.

Only enhancements applied to the MCP server side.

​Latest

​Summary

The Model Context Protocol (MCP) is a standardized protocol that enables AI models to interact with external tools and resources in a structured and consistent manner. It supports multiple transport mechanisms to ensure flexibility across various environments.

Please note that MCP is currently under rapid development. Concepts and APIs may change significantly, and backward compatibility cannot be guaranteed.

As this is an experimental feature, it must be enabled manually!

Currently, MCP alone does not meet enterprise-level requirements, such as strict access control,even after breaking changes introduced in MCP Java SDK 0.8.0 ⚠️. To address this, ApiHug provides key enhancements:

1. Enterprise-grade security: Full access control aligned with existing enterprise architecture.
2. Minimal integration impact: Leverages current infrastructure and standards with minimal system changes.

Based on Spring AI, ApiHug introduces the following enhancements:

1. Custom transport provider: Seamlessly injects custom authorization and session management.
2. Adapter layer: Bridges existing backend services to MCP standards without affecting current logic.
3. Unified resource control: Applies consistent validation and authorization mechanisms.
4. Fine-grained exposure control: Specifies which resources are exposed via MCP, down to the individual API level.

​Migration

​libs.versions.toml

1. Upgrade apihugVersion to 1.4.0-RELEASE or later.
2. Upgrade springAiVersion to 1.0.0 or later. If missing, add it.
3. Add the following libraries:
   • apihug-spring-ai-mcp = { group = "com.apihug", name = "it-common-spring-ai-mcp" }
   • spring-ai-bom = { group = "org.springframework.ai", name = "spring-ai-bom", version.ref = "springAiVersion" }
   • spring-ai-starter-mcp-server = { group = "org.springframework.ai", name = "spring-ai-starter-mcp-server" }

​app Module

1. Enable hopeStub: set enableMcp = true
2. Add the following dependencies:

// For MCP — current version under review
implementation(libs.apihug.spring.ai.mcp)
implementation platform(libs.spring.ai.bom)
implementation(libs.spring.ai.starter.mcp.server)

​Service Loader

To extend hope.common.service.contract.ContractAdapter, you need to define:

1. moduleClassName: The runtime proto module class name (self-contained).
2. mcp: Controls service exposure via MCP — specifies which service exposes which method (API).
3. contract: Defines third-party module dependencies — which service depends on which method (API).

Service Filter DSL:

  return myModule.service()
          .apiContext()
          .orderService(
              svc -> {
                // Keep all the methods of this service
                svc.keepAll();
                // All the method start with, feel free try other shortcut
                svc.startsWith("add");
                // Pick method one by one
                svc.methods(
                    methods -> {
                      // Include this method
                      methods.PlaceOrder();
                      // Exclude this method, start with `_`
                      methods._DeleteOrder();
                    });
              })
          .build();

​Spring Server AI Configuration

Follow the official MCP Server Boot Starter documentation to enable the MCP server.

spring:
  ai:
    mcp:
      server:
        enabled: true
        # default /sse
        sse-endpoint: /api/mcp/sse
        # default /mcp/message
        sse-message-endpoint: /api/mcp/message
        name: okai-app-mcp-server
        stdio: false
hope:
  ai:
    mcp:
      enabled: true
      auth-key: token

For configuration details related to spring.ai.mcp.server, please refer to the official documentation:
MCP Server Boot Starter - Configuration Properties.

Note: Please ensure that the SSE endpoint and message endpoint are configured using paths that align with your team’s best practices and standards.

The following two routes will be implemented:

1. GET /api/mcp/sse
2. POST /api/mcp/message

For instructions on how to perform local MCP testing, please refer to the Spring example:

spring-ai-examples - test - ClientSse.

Everything is set! Happy coding and enjoy your development! Bon appétit🍀

​New Template

Upgrade your IDEA plugin to version 0.7.5 or later. Newly generated projects will include all necessary configurations automatically, eliminating the need for manual migration steps required by legacy projects.

​Demo

TBD

​Refer

1. MCP Server Boot Starter
2. Model Context Protocol
3. MCP Java SDK