xpert-plugin-development skill in xpert-skills provides engineering conventions and implementation guidance. This tutorial uses a fictional business query plugin to explain the development logic from business capability to MCP invocation, including how the platform supports plugin-defined configSchema.
Define the business capabilities first
Assume Doris already has abiz_order table containing an order number, site, status, amount, update time, and active flag. The plugin exposes three read-only operations and one schema resource:
Development starts with these contracts. For example,
get_orders defaults limit to 100 and include_inactive to false. Its result includes data, the number of rows returned in this batch as rowCount, and a truncated flag. Monetary precision, null handling, and stable ordering are also part of the contract.
The database host, password, and configured row cap belong to connection settings, so callers do not supply them with every query. The query implementation restricts access to allowed tables and binds filter values as parameters. A site filter is a query condition; data access permissions still require separate enforcement.
How the skill, plugin, and platform divide the work
Development usesxpert-plugin-development from the official xpert-skills repository, consulting its native MCP and MCP service configuration references as needed. The skill guides a development agent through the target SDK, project structure, implementation, and verification. At runtime, the platform loads and executes the plugin.
With these responsibilities established, development produces the business contracts, shared query service, tool declarations, configuration definition, and verification cases. The skill’s guidance must be checked against the target platform and SDK versions, particularly for MCP configuration tabs and save validation. Loading a skill does not add those capabilities to an older platform.
How a business method becomes an MCP tool
The plugin first places connection resolution, queries, and result conversion in a shared business service. It then declares capabilities through a native Tool Provider.@XpertToolProvider() describes the Provider, while @XpertTool() describes callable methods, their inputs, and read/write annotations. A resource declaration exposes the table schema.
When the platform loads the plugin, it discovers these declarations and registers the tools and resources. The plugin entrypoint, dependencies, manifest, and build outputs must also be complete so that the declarations and implementations reach the installed package. See Host-Native MCP Tools for the interfaces.
For external access, an MCP Publication combines selected capabilities and their source instances into an MCP service. A client connects to that service URL, and the platform routes each tool invocation to its plugin method. The platform handles Streamable HTTP, identity verification, permission policies, and audit, allowing the business plugin to focus on query behavior.
Plugin installation, capability registration, and MCP publication are therefore connected stages: installation brings code into the platform, registration makes capabilities discoverable, and publication determines which service exposes them.
Describe the required settings with configSchema
This example defines a ProviderconfigSchema with the title Connection settings. The schema describes fields and rules; the platform persists the actual connection values entered into the form.
Field types, labels, conditional visibility, and control metadata come from the plugin’s schema. The platform renders them with its shared form system, so this business plugin does not need a separate connection page. The plugin obtains data source choices through the existing data source capability and filters by the explicit Doris engine type. Opening a data source still checks the current caller’s permissions.
The two modes have explicit execution paths. Platform mode opens an adapter through the data source runtime capability, with credentials managed by the platform. Manual mode uses the Doris plugin’s public connection factory. A failed connection should return its error instead of silently switching to another configuration.
The plugin also needs configuration parsing and business validation. For example, manual mode requires a host and database, while platform mode requires a selected data source.
validateConfig checks values before saving; parsing before execution handles defaults, existing settings, and current runtime conditions.
Each setting must affect business behavior. The effective get_orders row limit is the smaller of the invocation’s limit and the instance’s maxRows. The query adapter receives queryTimeoutMs. This connects the form’s settings to actual query behavior.
Where settings live and how tabs are distinguished
An instance here means a platform toolset instance, with its owntoolsetId, name, and settings. One plugin can have multiple instances that reuse the same tool implementation and schema while storing separate connection values.
For example, an order query plugin might have East region orders and South region orders instances connected to different databases. The MCP service uses the settings of whichever instance supplies the invoked capability.
The platform generates these tabs from each bound instance’s Provider
configSchema. The plugin can define the title. When there is more than one configuration tab, the platform adds the instance name, such as Connection settings · East region orders and Connection settings · South region orders. The form also identifies the instance and plugin package, so clear instance names help distinguish them. A source without configuration fields does not automatically contribute a configuration form tab.
Opening a tab loads the bound instance’s existing values. Saving updates that instance. It does not create another connection or copy the settings into other toolsets in the service.
Development also needs to distinguish several similarly named configuration definitions:
These definitions can reuse fields, but their values have separate ownership and access paths.
From saving settings to executing a query
The platform connects configuration management and tool execution through the same source instance: When saving, the platform checks management permissions, validates values against the schema and Provider rules, and updates the instance. Saved passwords appear as masks; leaving a mask unchanged preserves the existing value. Configuration revisions detect concurrent edits so an older form cannot overwrite newer settings. During invocation, the platform resolves the published capability’s boundtoolsetId and exposes its settings through context.host.credentials. The plugin reads the values for that invocation’s instance, then obtains an adapter for the selected connection mode. Credentials do not need to appear in MCP tool descriptions or client-supplied arguments.
For example, if East region orders has maxRows=5, a client calling get_orders(limit=100) receives at most five rows. Another instance configured with maxRows=50 continues to use its own cap. A plugin that caches connections must isolate them by instance and configuration and invalidate them when settings change to preserve this behavior.
Reuse the capabilities in a digital assistant
If a platform assistant also needs order queries, middleware can reuse the same business service and tool methods. An assistant template assembles the required middleware and business instructions, with connection details configured when it is used. Code reuse does not automatically share configuration. MCP calls read settings from the bound toolset instance, while middleware reads its own options. Both paths can reuse field definitions and connection parsing logic. The template includes only the required business capabilities and contains no connection credentials.What verification needs to establish
Verification covers declarations, configuration, and actual execution:
These checks provide different evidence. Builds and lifecycle tests establish that the plugin can load. API and integration tests establish configuration and invocation behavior. UI verification establishes the editing experience. The skill guides development, while actual results on the target platform confirm the implementation.
For field controls, see Schema UI Extensions. For client connections, see Platform MCP Services.