MCP Tool API
Reference
The MCPTool interface (org.xwiki.contrib.llm.mcp.MCPTool), annotated @Role and @Unstable, is the extension point for contributing tools to the XWiki MCP server.
The component hint is the tool's stable id, and it must be exactly the string the tool advertises as McpSchema.Tool.name(). The administration tool tree and the default policy build the enabled set from hints, while registration, the man catalog and the logs match on the advertised name. A hint that differs from the name silently drops the tool from every wiki: the name is never in the enabled set that registration filters on.
| Member | Returns | Default | What it does |
|---|---|---|---|
| getToolDefinition() | McpSchema.Tool | required | The name, description and input JSON schema advertised to the model. The name must equal the component hint. |
| execute(McpSchema.CallToolRequest) | McpSchema.CallToolResult | required | Runs one tool call and returns its result. |
| isEnabled() | boolean | true | Global kill switch: a disabled tool is registered on no wiki. |
| isWrite() | boolean | false | Whether the tool modifies wiki content. A tool that creates, changes or deletes content must return true: the default policy leaves write tools off per wiki, and the guest variant never registers them. |
| getCategory() | String | "General" | The group the tool appears under in the man catalog. |
| getSummary() | String | null | The catalog tagline and the NAME line. When null, man falls back to the first sentence of the definition's description. |
| getManPage() | String | null | The long-form prose man appends below the generated sections, kept out of the definition so it is not shipped on every call. |
Contracts the signature does not show
The definition is sent to the model on every request, so it stays lean. The manager meta-validates its input and output schemas at registration with the SDK's validator; a malformed schema skips that tool with a WARN instead of failing the whole server build.
execute runs as the calling wiki user on the request thread. When the wiki allows guest access, that user can be the guest user, in which case the tool can read only what a guest may read. A tool whose isWrite() is true is never run for a guest: the guest server variant does not register it, and executeWrapped refuses it as a second line of defence.
Failure is reported as an isError result whose message names the corrective action, not as an exception. The one exception is an unexpected RuntimeException or LinkageError, which the middleware normalizes into a generic error result so internals do not leak through the transport.
Tool ids the server reserves
man is mandatory: it is always in the effective tool set, even when a wiki stores an explicit list that omits it. list_wikis is reach-gated: it is present exactly when the wiki has cross-wiki reach enabled, and the administration tree never offers it as a toggle. Contributed tools follow the same isWrite() rule as the bundled ones. The index module contributes list_collections and search_collections when it is installed, both under Semantic Search and both read-only.
The full list of tools, bundled and contributed, is on MCP Tools. Create a New MCP Tool shows the component skeleton those two required members go in.
FAQ
How does a tool declare its parameters?
Through MCPToolSupport, which produces the advertised input schema and the typed accessors from one declaration. A hand-written schema is what lets the advertised parameters drift from the ones the tool reads.
Where are the rules for the text these methods return?
On Tool Man Pages: what man renders from each member, and the wording rules the bundled tools follow for descriptions and error messages.
Does a new tool need a server change?
No compile-time change: the manager enumerates MCPTool components when it builds a wiki's cached server. A newly installed component is picked up when that server is rebuilt, which happens on the next save of the wiki's MCP configuration page or on a restart.
