Package akka.javasdk.annotations.mcp

Annotation Interface McpTool

@Target(METHOD) @Retention(RUNTIME) @Documented public @interface McpTool
Annotation to expose a method as an MCP tool that can be called by MCP clients.

MCP tools are functions that AI models can invoke to perform specific tasks or retrieve information. The LLM determines which tools to call based on the tool descriptions and the user's request.

Method Requirements:

  • Must be public
  • Can return a String, an object type, an array or collection, or nothing. See the return types below.
  • Can accept 0 or more parameters
  • Must be in a class annotated with McpEndpoint

Parameter Types: Only simple parameter types are supported. Fields must be primitive types, boxed Java primitives, or strings. All parameters are required by default; use Optional<T> for optional parameters.

Schema Generation: The input schema is automatically generated from method parameters unless a manual schema is provided via inputSchema(). Use Description annotations on parameters to help the LLM understand their purpose.

Return Types:

  • The endpoint sends a String return value to the client as text content.
  • For an object type, such as a record, the tool listing contains an output schema generated from the fields of the type. The endpoint sends the object as structured content.
  • For an array or a collection, the output schema is an object with a single result field, and the endpoint sends the elements in the result field of the structured content.
  • For a Map, the output schema is an object without properties.
  • For a void method, the endpoint sends the text SUCCESS.
  • For other types, such as primitives, enums and dates, the endpoint sends the JSON of the value as text content.
  • A method can return a CompletionStage of any of the types above. The endpoint sends the result when the stage completes.

The endpoint also sends structured content as JSON text content, for clients that do not support structured content. The endpoint leaves fields with an empty Optional or a null value out of the structured content. A null return value fails the tool call. A protobuf message, or a type that contains one, is not a valid return type and fails when the service starts.

Best Practices:

  • Provide clear, descriptive tool descriptions
  • Use Description on all parameters
  • Keep tools focused on single, well-defined tasks
  • Validate input parameters for security
  • Use ToolAnnotation to describe tool behavior characteristics

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    description
     

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    ToolAnnotation[]
    annotations
    Optional annotations describing what the tool does to the client.
    String
    inputSchema
    Normally, the schema is inferred from the input parameters of the tool method.
    String
    name
     

  • Element Details

    • name

      String name
      Returns:
      The name of the tool. Must be unique in the same MCP endpoint if specified, if not specified, the method name is used.
      Default:
      ""

    • description

      String description
      Returns:
      A clear description of what the tools, used by the client LLM to determine what the tool can be used for

    • inputSchema

      String inputSchema
      Normally, the schema is inferred from the input parameters of the tool method.
      Returns:
      A manually specified schema instead of the automatic must match the input parameters and how they are parsed by Jackson.
      Default:
      ""

    • annotations

      ToolAnnotation[] annotations
      Optional annotations describing what the tool does to the client.
      Default:
      {}