Skip to main content
v2

MCP HTTP Tool

ConvEngine supports two HTTP MCP integration models.

Two ways​

HTTP MCP models

ModelUse whenHow it executes
HttpApiRequestingToolHandlerYou want framework-managed retries/timeouts/circuit/auth/mappingHttpApiToolInvoker (framework HttpClient)
HttpApiProcessorToolHandlerYou already use [api-processor](https://github.com/salilvnair/api-processor) in your appRestWebServiceFacade -> delegate.invoke -> processResponse

Related libraries:

Model A: HttpApiRequestingToolHandler​

Flow​

  1. Handler returns HttpApiRequestSpec
  2. Framework executes HTTP call
  3. Mapping mode resolves output
  4. MCP observation is stored

Supported mapping modes:

  • RAW_JSON
  • JSON_PATH
  • FIELD_TEMPLATE
  • MAPPER_CLASS
  • TEXT

MAPPER_CLASS example:

new HttpApiResponseMapping(
        HttpApiResponseMappingMode.MAPPER_CLASS,
        null,
        Map.of(),
        "com.acme.api.OrderStatusResponse");

Model B: HttpApiProcessorToolHandler​

Flow​

  1. wsContext(...) builds tool context
  2. wsHandler(...) returns RestWebServiceHandler
  3. Framework calls RestWebServiceFacade.initiate(...)
  4. prepareRequest(...) runs
  5. delegate invoke(...) runs
  6. processResponse(...) maps output
  7. framework calls extractResponse(...) and stores MCP observation

convengine-demo package convention​

In demo we now keep each api-processor MCP tool in its own folder tree with dedicated handler/delegate:

  • mcp/handler/loan/credit/rating/...
  • mcp/handler/loan/credit/fraud/...
  • mcp/handler/loan/application/submit/...
  • mcp/handler/mock/customer/profile/...
  • mcp/handler/mock/order/status/...
  • mcp/handler/mock/order/async/trace/...
  • mcp/handler/mock/order/submit/...

Each tool folder contains:

  • <Tool>ToolHandler (MCP SPI class)
  • handler/<Tool>WsHandler
  • delegate/<Tool>WsDelegate

Shared lightweight helper types are in:

  • mcp/handler/common/...
Debt tool intentionally unchanged

As requested, LoanDebtSummaryToolHandler remains HttpApiRequestingToolHandler to demonstrate the framework-managed HTTP model side-by-side with api-processor mode.

What MockOrderAsyncTraceToolHandler does​

mock.order.async.trace fetches async callback trace details for an order:

  • traceId
  • api4AsyncStatus
  • callbackReceivedAt
  • message

It is used in order diagnostics flow to explain why an order can be submitted while async callback is still pending or null.