MCP annotations
The nine MCP annotations that define an agent-facing server, its topics and its tools, with real examples.
Source: framework/mcp/src/com/ilscipio/scipio/mcp/def/. These annotations
define the MCP servers and tools an AI agent calls; see
Agents
for the access model.
@McpServer#
Defines one MCP server profile, usually one per application component.
| Attribute | Type | Default | Meaning |
|---|---|---|---|
name | String | required | Server name. |
title | String | "" | Human-readable title. |
description | String | "" | Server description, shown to the agent. |
component | String | "" | Component directory name the server belongs to. |
webapps | String[] | {} | Webapps the server is exposed on. |
featuredServices | String[] | {} | Services ranked first in tool search. |
serviceAllow | String[] | {} | Services explicitly allowed through the gateway. |
serviceDeny | String[] | {} | Services denied on this server. |
entities | String[] | {} | Entities the server may read through entity tools. |
allowAnonymous | boolean | false | Whether the server accepts calls without a token. |
requiredPermission | String | "" | Permission required to use the server. |
hub | boolean | false | Whether this is the cross-application hub server. |
topics | McpTopic[] | {} | Topics this server declares; a topic is one tool with an action argument. |
serviceTools | McpServiceTool[] | {} | Services wrapped directly as tools. |
providers | Class<? extends McpToolProvider>[] | {} | Tool providers that build tools at run time. |
@McpServiceTool#
Wraps one existing service as a tool, inside @McpServer(serviceTools = {...}) or @McpServerExtension(serviceTools = {...}).
| Attribute | Type | Default | Meaning |
|---|---|---|---|
service | String | required | Service name to wrap. |
name | String | "" | Tool name. Defaults to the service name in snake_case. |
description | String | "" | Tool description. Defaults to the service description. |
featured | boolean | false | Whether the tool is ranked first. |
order | int | 100 | Sort order among tools; lower first. |
readOnly | boolean | false | Whether the tool only reads data. |
destructive | String | "" | Whether the tool is destructive. |
idempotent | String | "" | Whether repeat calls are safe. |
permission | String | "" | Permission required, beyond the default gate. |
requiresConfirmation | boolean | false | Client-side confirmation hint. |
topic | String | "" | Topic this service tool joins. |
exclude | String[] | {} | Service parameters to hide from the tool schema. |
fixed | String[] | {} | Service parameters fixed to a set value. |
tags | String[] | {} | Free-form tags. |
@McpTool#
Marks a hand-written static method as one tool.
| Attribute | Type | Default | Meaning |
|---|---|---|---|
topic | String | "" | Topic this method joins. The topic is the tool the agent sees. |
name | String | required | Tool name, or, with a topic, the action value. |
title | String | "" | Human-readable title. |
description | String | required | Tool description, shown to the agent. |
featured | boolean | false | Whether the tool is ranked first. |
order | int | 100 | Sort order among tools; lower first. |
readOnly | boolean | false | Whether the tool only reads data. |
destructive | String | "" | Whether the tool is destructive. |
idempotent | String | "" | Whether repeat calls are safe. |
permission | String | "" | Permission required, beyond the default gate. |
access | McpAccess | McpAccess.AUTH | AUTH (token required) or PUBLIC. |
requiresConfirmation | boolean | false | Client-side confirmation hint. |
tags | String[] | {} | Free-form tags. |
@McpTopic#
Declares one topic: the tool an agent sees, with the methods of that topic as
its action values. Declare it on @McpServer(topics = ...) or
@McpServerExtension(topics = ...).
| Attribute | Type | Default | Meaning |
|---|---|---|---|
name | String | required | Topic name. This is the tool name the agent calls. |
title | String | "" | Human-readable title. |
description | String | "" | Topic description, shown to the agent. |
order | int | 100 | Sort order among tools; lower first. |
featured | boolean | false | Whether the topic is ranked first. |
@McpParam#
One parameter of an @McpTool method.
| Attribute | Type | Default | Meaning |
|---|---|---|---|
name | String | required | Parameter name. |
description | String | "" | Parameter description. |
required | boolean | true | Whether the parameter is required. |
enumValues | String[] | {} | Allowed values, if the parameter is an enum-like string. |
type | String | "" | Explicit type override for the schema. |
example | String | "" | Example value shown to the agent. |
@McpPrompt#
Defines one reusable prompt template the server exposes.
| Attribute | Type | Default | Meaning |
|---|---|---|---|
name | String | required | Prompt name. |
description | String | "" | Prompt description. |
arguments | Arg[] | {} | Prompt arguments (nested @Arg: name, description, required default false). |
@McpResource#
Defines one static or templated resource the server exposes.
| Attribute | Type | Default | Meaning |
|---|---|---|---|
uri | String | required | Resource URI, for example scipio://skills/<name>. |
name | String | required | Resource name. |
description | String | "" | Resource description. |
mimeType | String | "text/plain" | MIME type of the resource content. |
@McpServerExtension#
Adds tools to a server owned by another component, without changing that server’s source.
| Attribute | Type | Default | Meaning |
|---|---|---|---|
server | String | required | Name of the server to extend. |
featuredServices | String[] | {} | Extra featured services. |
serviceAllow | String[] | {} | Extra allowed services. |
serviceDeny | String[] | {} | Extra denied services. |
entities | String[] | {} | Extra entities. |
topics | McpTopic[] | {} | Extra topics this extension declares. |
serviceTools | McpServiceTool[] | {} | Extra services wrapped as tools. |
providers | Class<? extends McpToolProvider>[] | {} | Extra tool providers. |
@McpAccess#
Enum, not an annotation: the access level of one tool, used by
@McpTool(access = ...).
| Value | Meaning |
|---|---|
AUTH | Requires a valid token. |
PUBLIC | Available without a token when the server sets allowAnonymous = true. |
Example: the manufacturing server#
applications/manufacturing/src/com/ilscipio/scipio/manufacturing/mcp/ManufacturingMcp.java,
lines 27-40.
@McpServer(name = "manufacturing", title = "Scipio Manufacturing", component = "manufacturing",
description = "Manufacturing: explode a bill of material, find and inspect production runs, create a production run and change its status.",
featuredServices = {"createProductionRun", "updateProductionRun", "changeProductionRunStatus",
"createBOMAssoc", "updateProductManufacturingRule", "createMrpEvent", "getProductRouting", "getManufacturingComponents",
"quickRunAllProductionRunTasks", "executeMrp", "getWorkCenterLoad", "getManufacturingDashboard", "getShopFloorTasks",
"declareProductionRunTaskReject", "getProductionRunRejects", "getProductStandardCost", "getProductWhereUsed",
"createProductionRunsForOrder", "changeProductionRunTaskStatus", "updateProductionRunTask"},
entities = {"ProductManufacturingRule", "TechDataCalendar", "TechDataCalendarExcDay", "WorkEffortGoodStandard",
"TechDataCalendarExcWeek", "TechDataCalendarWeek", "MrpEventType", "MrpEvent", "MrpEventView", "MrpRun", "ProductionRunReject"},
serviceTools = {
@McpServiceTool(service = "createProductionRun", name = "production_run_create",
description = "Create a production run: productId, pRQuantity, startDate, facilityId, optional routingId and workEffortName.",
featured = true, readOnly = false, destructive = "false", requiresConfirmation = true, order = 40),
@McpServiceTool(service = "changeProductionRunStatus", name = "production_run_update_status",
description = "Move a production run to the next status (PRUN_SCHEDULED, PRUN_DOC_PRINTED, PRUN_RUNNING, PRUN_COMPLETED, PRUN_CLOSED) or to the given statusId.",
featured = true, readOnly = false, destructive = "true", requiresConfirmation = true, order = 50),The server declares its name, the entities it may read, and a set of existing services wrapped directly as tools with agent-facing names and descriptions.
Example: an @McpTool method#
applications/accounting/src/com/ilscipio/scipio/accounting/mcp/AccountingMcp.java.
@McpTool(topic = "invoice", name = "find", description = "Find invoices by id, type, status, party or invoice date range.",
readOnly = true, order = 10)
public static Object findInvoices(McpCallContext ctx,
@McpParam(name = "invoiceId", required = false) String invoiceId,
@McpParam(name = "invoiceTypeId", description = "e.g. SALES_INVOICE, PURCHASE_INVOICE", required = false) String invoiceTypeId,
@McpParam(name = "statusId", description = "e.g. INVOICE_IN_PROCESS, INVOICE_READY, INVOICE_PAID", required = false) String statusId,
@McpParam(name = "partyId", description = "Bill-to party (partyId) or bill-from party (partyIdFrom)", required = false) String partyId,
@McpParam(name = "fromDate", description = "Invoice date on/after", required = false) Timestamp fromDate,
@McpParam(name = "thruDate", description = "Invoice date on/before", required = false) Timestamp thruDate,
@McpParam(name = "limit", required = false) Integer limit) throws McpToolException {Every parameter but ctx carries an @McpParam. None is required, so the
agent can call the tool invoice with action find and any subset of
filters.
Topics: one tool, many actions#
An application has hundreds of operations and an agent works better with few
tools. @McpTopic groups them: the methods that name the same topic become
one tool, and the method’s name becomes the action argument of that tool.
The install ships 31 application topics with 318 actions, plus six core tools.
@McpServer(name = "order", topics = {
@McpTopic(name = "order", description = "Sales and purchase orders: find, create, approve, pay, ship, return."),
@McpTopic(name = "purchase_order", description = "Requirements, purchase orders and their supplier."),
@McpTopic(name = "quote", description = "Quotes and customer requests.")
})
public final class OrderMcp { }topic exists on @McpTool and on @McpServiceTool; topics exists on
@McpServer and on @McpServerExtension. A method with no topic stays a
tool of its own.