Skip to content

Commit d75362d

Browse files
docs: Explain Axis2 JSON envelope translation in MCP bridge section
Replace terse one-liner with explanation of how the bridge translates between standard MCP JSON-RPC 2.0 and Axis2's internal JSON convention, including why the arg0 wrapper and array envelope exist (SOAP/XML heritage via Axiom OMElement tree). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent c15a4bf commit d75362d

1 file changed

Lines changed: 11 additions & 2 deletions

File tree

src/site/markdown/docs/mcp-architecture.md

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -211,8 +211,17 @@ handshake is straightforward enough to hand-roll correctly.
211211
**Build**: maven-shade-plugin 3.6.0 produces `axis2-mcp-bridge-2.0.1-SNAPSHOT-exe.jar`
212212
(classifier: `exe`) with `MainClass=McpBridgeMain`.
213213

214-
**Axis2 JSON-RPC envelope**: `tools/call` wraps arguments as `{toolName: [arguments]}`
215-
before POSTing to the Axis2 endpoint, matching the existing JSON-RPC convention.
214+
**Axis2 JSON envelope translation**: The bridge translates between standard MCP
215+
JSON-RPC 2.0 and Axis2's internal JSON convention. MCP sends clean named parameters
216+
(`{"nAssets":5, "weights":[...]}`); the bridge wraps them into the envelope that
217+
Axis2's `JsonRpcMessageReceiver` expects: `{"operationName":[{arguments}]}`. The
218+
array wrapper and operation-name-as-key pattern are artifacts of Axis2's SOAP/XML
219+
heritage — the JSON formatter maps the request body to an Axiom `OMElement` tree
220+
where the operation name is the root element and each array entry corresponds to
221+
a Java method parameter. When the service method takes a single POJO argument,
222+
callers see `{"operationName":[{"arg0":{...}}]}` where `arg0` is the default WSDL
223+
parameter name. The bridge hides this from AI clients so they see only standard
224+
JSON-RPC 2.0.
216225

217226
**Notifications**: MCP `notifications/initialized` (no `id` field) is silently consumed
218227
with no response, as required by JSON-RPC 2.0.

0 commit comments

Comments
 (0)