Add an MCP tool
Add a tool to the workspace MCP endpoint that maps onto one HTTP handler, returns only contract fields, and requires the workspace admin role.
The workspace MCP endpoint lets an MCP client, such as Claude Code, read a workspace's practice configuration for an admin. ADR 0110 owns the design, the tool list and the data contract. The admin guide tells operators how to turn it on.
A tool is a Spring bean that implements core.mcp.McpTool.
The MCP server registers every such bean on the server role.
The tool runs on the request thread, so the workspace context and the authentication of the request apply.
Steps
- Choose the HTTP handler that the tool stands for. A tool adds no second path: it calls that handler's service.
Declare it on the class with
@McpToolFor(controller = …, method = "…"). A handler that needs@RequiresRecentSignInor the instance-admin role cannot have a tool. - Put the tool in the module of the handler, in its
mcppackage, such aspractices.mcp. The module allowscore::mcp-spiin itspackage-info.java. - Put
@RequireAtLeastWorkspaceAdminon thecallmethod. Every tool needs the admin role, even if its handler lets any member read. A handler that requires more than admin, such as the owner role, cannot have a tool.McpToolHandlerParityArchTestchecks both rules. - Write the input and output JSON Schemas by hand as text blocks, and build the definition with
McpTools.readTool. Every object in the output schema has"additionalProperties": falseand requires every property. The SDK validates each result against the output schema, so a field outside the schema fails the call. - Return a projection, never a DTO. Build records that hold only the fields of the data contract.
Leave out text that a developer or a provider wrote: titles, bodies, comments, branch names, display names, channel and collection names, and free-text error messages.
Send a stored reason only when it is code-shaped;
McpProjections.codeturns anything else intoUNKNOWN. - Say in the description which fields hold configuration text, such as
criteria, and that a client treats them as data. - Add a row to the data contract in ADR 0110 for any field of a new class, and the reverse tool for any write.
- Test the tool over real HTTP in an integration test that connects a client with
McpAuthorizationFlow, asMcpPracticeToolsIntegrationTestdoes. Assert on what the tool returns, and on the rows that a write tool created.
What a refusal looks like
A tool does what its name says, or it refuses and says why.
A refused role check or a ResponseStatusException from the service becomes a tool result with isError: true and the reason as its text.
Never map a request to a different effect.
Check that it worked
From server/, run the tests that guard every tool:
./gradlew :application:architectureTest --tests '*McpToolHandlerParityArchTest'
./gradlew :application:integrationTest --tests '*McpPracticeToolsIntegrationTest'The architecture test fails when the tool lacks the admin role or stands for a handler that needs more. The integration test fails when an output schema leaves an object open or a property optional. Your own integration test shows that a client finds the tool when it lists the tools, and that a call returns only contract fields.