2.1 _meta Block

{
  "_meta": {
    "axis2JsonRpcFormat": "{\"<operationName>\":[{\"arg0\":{<params>}}]}",
    "contentType":        "application/json",
    "authHeader":         "Authorization: Bearer <token>",
    "tokenEndpoint":      "POST /services/loginService/doLogin",
    "errorContract": {
      "schemaRef": "#/components/schemas/ErrorResponse",
      "fields": {
        "error":      "Error code: VALIDATION_ERROR | RATE_LIMITED | SERVICE_UNAVAILABLE | BAD_REQUEST | INTERNAL_ERROR",
        "message":    "Human-readable error message",
        "errorRef":   "UUID correlation ID — quote in support requests",
        "timestamp":  "ISO 8601 when the error occurred",
        "retryAfter": "Seconds to wait before retrying (429/503 only, null otherwise)"
      },
      "httpStatusMapping": {
        "400": "BAD_REQUEST — malformed JSON or missing required fields",
        "422": "VALIDATION_ERROR — valid JSON but fails business validation",
        "429": "RATE_LIMITED — too many requests, check retryAfter",
        "500": "INTERNAL_ERROR — server fault, errorRef logged server-side",
        "503": "SERVICE_UNAVAILABLE — downstream dependency or overload"
      }
    }
  },
  ...
}

The _meta block answers the three questions every MCP client must answer before calling any tool:

• What body structure does the server expect? See axis2JsonRpcFormat — the Axis2 JSON-RPC envelope with operation name as the top-level key.
• How do I authenticate? See authHeader and tokenEndpoint — call loginService/doLogin first, then pass the returned token as a Bearer header.
• What Content-Type? Always application/json.
• What do errors look like? See errorContract — structured JSON with error code, message, correlation ID (errorRef), timestamp, and HTTP status mapping. Services throw JsonRpcFaultException to produce these responses.

2.2 Per-Tool Fields

{
  "tools": [
    {
      "name":        "doLogin",
      "description": "loginService: doLogin",
      "inputSchema": {
        "type":       "object",
        "properties": {},
        "required":   []
      },
      "endpoint":                "POST /services/loginService/doLogin",
      "x-axis2-payloadTemplate": "{\"doLogin\":[{\"arg0\":{}}]}",
      "x-requiresAuth":          false,
      "annotations": {
        "readOnlyHint":    false,
        "destructiveHint": false,
        "idempotentHint":  false,
        "openWorldHint":   false
      }
    },
    {
      "name":        "portfolioVariance",
      "description": "Calculate portfolio variance using O(n^2) covariance matrix multiplication",
      "inputSchema": {
        "type": "object",
        "required": ["nAssets", "weights", "covarianceMatrix"],
        "properties": {
          "nAssets":          {"type": "integer", "minimum": 2, "maximum": 2000},
          "weights":          {"type": "array", "items": {"type": "number"}},
          "covarianceMatrix": {"type": "array", "items": {"type": "array", "items": {"type": "number"}}},
          "normalizeWeights": {"type": "boolean", "default": false},
          "nPeriodsPerYear":  {"type": "integer", "default": 252}
        }
      },
      "endpoint":                "POST /services/FinancialBenchmarkService/portfolioVariance",
      "x-axis2-payloadTemplate": "{\"portfolioVariance\":[{\"arg0\":{}}]}",
      "x-requiresAuth":          true,
      "annotations": {
        "readOnlyHint":    true,
        "destructiveHint": false,
        "idempotentHint":  true,
        "openWorldHint":   false
      }
    }
  ]
}

Field semantics:

MCP 2025-03-26 annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) are present for spec compliance but are all false. They are not tuned per service. If your MCP host requires accurate hints, you must set them in a catalog post-processor or in your Python MCP server layer.

3.1 Required Envelope Structure

POST /services/{ServiceName}/{operationName}
Content-Type: application/json
Authorization: Bearer {token}

{
  "{operationName}": [
    {
      "arg0": {
        ... your parameters here ...
      }
    }
  ]
}

The parsing sequence in JsonUtils.invokeServiceClass() is strict:

1. beginObject() — outer {}
2. nextName() — must equal the operation name
3. beginArray() — the [...] wrapper
4. beginObject() — the parameter object
5. nextName() → fromJson() — reads each parameter
6. endObject(), endArray(), endObject()

Any deviation — bare JSON object, missing array, wrong operation name — results in Bad Request [errorRef=<uuid>]. There is no partial match or helpful field-level error (see Section 5).

3.2 Login Payload Example

The exact payload for loginService/doLogin:

{
  "doLogin": [
    {
      "arg0": {
        "email":       "user@example.com",
        "credentials": "password"
      }
    }
  ]
}

This pattern applies to every Axis2 service. The x-axis2-payloadTemplate field in the catalog pre-fills the operation name wrapper so MCP clients only need to substitute parameters into arg0.

3.3 enableJSONOnly Mode

When a service is deployed with enableJSONOnly=true, the outer operation name wrapper is optional — the server dispatches by URL path alone. The payload reduces to:

[{ "arg0": { ... parameters ... } }]

Most production deployments use enableJSONOnly=false (the default), which requires the full envelope. Check the catalog's x-axis2-payloadTemplate to see which format a specific service expects.

Phase 1 — Obtain Token (no auth required)

POST /services/loginService/doLogin
Content-Type: application/json

{
  "doLogin": [
    {
      "arg0": {
        "email":       "user@example.com",
        "credentials": "password"
      }
    }
  ]
}

Response:
{
  "response": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "user": { ... }
  }
}

Token storage is implementation-specific. A common pattern is to persist the token as a JSON file with mode 0600 (user-only read), or pass it via an environment variable.

Phase 2 — Call Protected Services

POST /services/{ServiceName}/{operationName}
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

{
  "{operationName}": [{ "arg0": { ... } }]
}

All services except loginService require the Bearer header. The catalog's x-requiresAuth field encodes this per-tool. The _meta.tokenEndpoint tells MCP clients where to obtain the token without hardcoding the service path.

5.1 Structured JSON Errors (service-level validation)

Services that throw JsonRpcFaultException produce structured JSON error responses with proper HTTP status codes:

HTTP 422
Content-Type: application/json

{
  "response": {
    "status":     "FAILED",
    "error":      "VALIDATION_ERROR",
    "message":    "initialValue must be > 0 (GBM is undefined for non-positive starting values).",
    "errorRef":   "a3f2c1d0-7b4e-4a2f-9c8d-1e6f3b5a2d7c",
    "timestamp":  "2026-05-15T14:30:00Z",
    "retryAfter": null
  }
}

The HTTP status codes map to error categories:

The errorRef UUID is logged server-side with full context (operation name, exception message, stack trace). Clients should surface the UUID in their error displays so users can quote it in support requests.

5.2 SOAP Fault Fallback (parse-level errors)

Requests that fail before reaching the service method (malformed JSON, wrong operation name, missing array wrapper) produce a legacy SOAP fault with a sanitized Bad Request message. This is a deliberate security feature — no structural information leakage:

HTTP 500
<soapenv:Fault>
  <faultcode>soapenv:Server</faultcode>
  <faultstring>Bad Request [errorRef=a3f2c1d0-7b4e-4a2f-9c8d-1e6f3b5a2d7c]</faultstring>
</soapenv:Fault>

5.2 What Triggers This

5.3 Python MCP Implications

MCP tools built against Axis2 services should surface the errorRef UUID in their error responses so users can correlate with server logs. A recommended pattern is to return a structured ErrorResponse with error_type and suggestions:

from dataclasses import dataclass

@dataclass
class ErrorResponse:
    error:      str        # "Bad Request [errorRef=a3f2c1d0...]"
    error_type: str        # "axis2_payload_error"
    suggestions: list[str] # ["Check x-axis2-payloadTemplate in catalog"]