ApiHug MCP

ApiHug MCP support is an enterprise-oriented adapter layer for exposing existing services through the Model Context Protocol without abandoning the project’s existing authorization and service model.

What It Is

ApiHug adds MCP-specific integration on top of the normal application stack:

• transport hooks for authentication and session control
• an adapter layer that maps existing backend services into MCP exposure rules
• fine-grained service and method filtering
• Spring AI server integration

Why It Matters

Raw MCP support is useful, but enterprise systems usually need more than a bare protocol endpoint. ApiHug focuses on the missing pieces:

• alignment with existing access control
• minimal disruption to current service architecture
• explicit control over which APIs become MCP tools or resources

How It Fits

For older projects, enable MCP in three places.

1. Update the version catalog

Add or update the MCP-related entries in libs.versions.toml:

• 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" }

2. Enable it in the application module

Turn on MCP support in hopeStub and add the runtime dependencies:

hopeStub {
  enableMcp = true
}

dependencies {
  implementation(libs.apihug.spring.ai.mcp)
  implementation platform(libs.spring.ai.bom)
  implementation(libs.spring.ai.starter.mcp.server)
}

3. Define the service exposure surface

Extend hope.common.service.contract.ContractAdapter and describe:

• moduleClassName for the runtime proto module
• mcp exposure rules for services and methods
• contract dependencies on third-party modules

Example service filter DSL:

return myModule.service()
    .apiContext()
    .orderService(
        svc -> {
          svc.keepAll();
          svc.startsWith("add");
          svc.methods(
              methods -> {
                methods.PlaceOrder();
                methods._DeleteOrder();
              });
        })
    .build();

4. Configure the Spring AI MCP server

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

That exposes two main routes:

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

Newer project templates can include this wiring for you. Older projects need the migration steps above.

Next Step

1. Review Tool Chain if you need the rest of the ApiHug runtime surface
2. Read the official Spring AI MCP server docs before tuning transport details