Class MCPServlet

Servlet that exposes SmartClient DataSource operations over HTTP using the Model Context Protocol (MCP) and JSON-RPC 2.0.

This servlet is intended for machine-driven clients (for example AI agents, command-line tools or other backend services) that need a compact, schema-driven interface to the DataSources configured on the server. Application code normally interacts with DataSources directly via DSRequest and DSResponse; this servlet provides an HTTP façade for external consumers.

JSON-RPC methods

The servlet accepts HTTP POST requests with Content-Type: application/json and a standard JSON-RPC 2.0 envelope. The supported method values are:

• "tools/list" – discovers all DataSource-backed MCP tools and their JSON Schema input definitions.
• "tools/call" – executes a single tool (for example "ds.order.fetch") and returns the corresponding DataSource response.

Tool naming

For each defined DataSource with id <id>, this servlet exposes zero or more tools named:

• ds.<id>.fetch
• ds.<id>.add
• ds.<id>.update
• ds.<id>.remove
• ds.<id>.fetchAdvanced (only if the DataSource reports support for advanced criteria and/or aggregation)

A client can use "tools/list" once to discover the available tool names for each DataSource and then call those tools repeatedly via "tools/call".

"tools/list" result

The result for "tools/list" is an object containing:

• tools – an array of tool descriptors. Each descriptor includes:
  • name – the tool name (for example "ds.order.fetch").
  • description – a short human-readable description.
  • inputSchema – a JSON Schema fragment describing the expected arguments object for that tool.
• definitions – shared JSON Schema definitions that can be referenced from tool schemas, including:
  • "record:<id>" – the record shape for a particular DataSource, derived from its DSField metadata.
  • "criteria" – flat criteria objects (field/value pairs).
  • "advancedCriteria" – nested AdvancedCriteria objects where supported.

"tools/call" parameters

The "tools/call" method expects a JSON-RPC params object of the form:

• name – the name of a tool previously reported by "tools/list" (for example "ds.order.fetch").
• arguments – an object matching the tool's inputSchema. Common members include:
  • criteria or advancedCriteria for filtering.
  • data for add / update payloads.
  • startRow / endRow for paging.
  • sortBy, and for advanced fetches, groupBy and summaryFunctions where the DataSource allows aggregation.

The servlet maps these arguments to a DSRequest, applies additional validations appropriate to each operation (for example forbidding AdvancedCriteria on simple fetch, or requiring non-empty criteria for update and remove), executes the request and converts the DSResponse back into MCP form.

Results and errors

On success, the JSON-RPC result contains a single content entry with type:"json" and text set to a serialized SmartClient-style payload (status, row range and data list). On failure, parameter and validation errors are reported as JSON-RPC error responses with an appropriate numeric code, a human-readable message and optional structured data (for example DataSource status and field-level errors).

This servlet is typically registered under an application-specific URL via web.xml or programmatic servlet registration. The HTTP contract and MCP methods described above are considered the supported external interface; all helper methods inside this class are internal implementation details.