include::{mod-loc}shared/all-attributes.adoc[]

:_mod-docs-content-type: ASSEMBLY
[id="assembly-mcp-tool-features_{context}"]
= MCP tool definition features in {registry}

[role="_abstract"]
You can store and manage MCP (Model Context Protocol) tool definitions as first-class artifacts in {registry}. You can use MCP tool features for central governance, version management, and discovery of MCP tools across your organization.

ifdef::service-registry-downstream[]
WARNING: This section describes Developer Preview features. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. For more information about the support scope of Red Hat Developer Preview features, see link:https://access.redhat.com/support/offerings/devpreview[Developer Preview Support Scope].
endif::[]

* xref:mcp-tool-features-overview_{context}[]
* xref:mcp-tool-configuration_{context}[]
* xref:mcp-tool-definition-schema_{context}[]
* xref:mcp-well-known-endpoints_{context}[]
* xref:creating-mcp-tool-artifact_{context}[]
* xref:mcp-validation-rules_{context}[]
* xref:mcp-compatibility-checking_{context}[]
* xref:mcp-automatic-label-extraction_{context}[]

// con-mcp-tool-features-overview
:_mod-docs-content-type: CONCEPT
[id="mcp-tool-features-overview_{context}"]
== Overview

[role="_abstract"]
The https://modelcontextprotocol.io/[Model Context Protocol (MCP)] defines a standard for servers to expose tools that language models can invoke. With MCP tools, models can interact with external systems, such as querying databases, calling APIs, or running computations.

{registry} provides a Tool Registry that stores MCP tool definitions with the following capabilities:

NOTE: Storing an `MCP_TOOL` definition in {registry} provides governance, versioning, and searchability for tool definitions. To make stored tools available to LLM clients such as Claude Desktop, you must also deploy the {registry} MCP server. For more information, see xref:getting-started/assembly-mcp-server-integration.adoc[MCP server integration].

Version management:: Track tool evolution with full version history.
Validation:: Ensure that tool definitions conform to the MCP specification.
Compatibility checking:: Detect breaking changes in tool input schemas.
Discovery:: Search for tools by name or input parameter.
Well-known endpoints:: Serve tool definitions at standard URLs.

.MCP tool registry endpoints and capabilities
[cols="1,1",options="header"]
|===
|Well-known endpoints
|Capabilities

a|
* `/.well-known/mcp-tools` (search tools)
* `/.well-known/mcp-tools/\{groupId}/\{artifactId}` (retrieve tool)

a|
* Store tool definitions as `MCP_TOOL` artifacts
* Search by name or input parameter
* Version management
* Validation and compatibility checking
|===

// ref-mcp-tool-configuration
:_mod-docs-content-type: REFERENCE
[id="mcp-tool-configuration_{context}"]
== Configuration

[role="_abstract"]
You can configure MCP tool features by using the following configuration properties.

[cols="2,1,3"]
|===
|Property |Default |Description

|`apicurio.mcp-tools.enabled`
|`false`
|Enables or disables MCP tool definition support (experimental)

|`apicurio.features.experimental.enabled`
|`false`
|Set to `true` to use experimental features such as MCP tools
|===

To enable MCP tool support, set both properties:

[source,properties]
----
apicurio.features.experimental.enabled=true
apicurio.mcp-tools.enabled=true
----

// ref-mcp-tool-definition-schema
:_mod-docs-content-type: REFERENCE
[id="mcp-tool-definition-schema_{context}"]
== MCP tool definition schema

[role="_abstract"]
Tool definitions follow the https://modelcontextprotocol.io/specification/2025-11-25/server/tools[MCP specification (2025-11-25)].

NOTE: The MCP specification has two authoritative sources: the formal https://github.com/modelcontextprotocol/specification/blob/main/schema/2025-11-25/schema.json[JSON schema] and the https://modelcontextprotocol.io/specification/2025-11-25/server/tools[specification docs]. In some cases, these sources diverge. The following table notes where {registry} validation follows the spec docs guidance rather than the formal JSON schema.

.Tool fields

[cols="1,1,1,3"]
|===
|Field |Type |Required |Description

|`name`
|string
|Yes
|Unique identifier for the tool (1-128 characters, alphanumeric + underscore/hyphen/dot)

|`title`
|string
|No
|Human-readable name for display purposes

|`description`
|string
|No
|Human-readable description of tool functionality

|`inputSchema`
|object
|Yes
|JSON Schema defining expected input parameters

|`outputSchema`
|object
|No
|JSON Schema defining expected output structure. _Described in the spec docs but not yet present in the formal MCP JSON schema._

|`annotations`
|object
|No
|Optional metadata annotations (audience, priority)

|`icons`
|array
|No
|Optional icons for display in user interfaces. _Described in the spec docs but not yet present in the formal MCP Tool JSON schema._ Passed through without validation.

|`execution`
|object
|No
|Optional execution-related properties such as task support. _Described in the spec docs but not yet present in the formal MCP Tool JSON schema._ Passed through without validation.
|===

.Input schema

The `inputSchema` field is a JSON Schema object with the following properties:

[cols="1,1,1,3"]
|===
|Field |Type |Required |Description

|`type`
|string
|Yes
|Must be `"object"`. The formal MCP JSON schema does not enforce this constraint, but the spec docs and all examples require it. {registry} enforces `type` = `"object"` during full validation.

|`properties`
|object
|No
|Parameter definitions (each value is a JSON Schema object)

|`required`
|array
|No
|List of required parameter names
|===

.Annotations (ToolAnnotations)

Annotations provide metadata about the tool by using the MCP `ToolAnnotations` type:

[cols="1,1,3"]
|===
|Field |Type |Description

|`title`
|string
|Optional fallback display name. Per the spec docs, display precedence is: top-level `title` -> `annotations.title` -> `name`. _Note: the spec docs reference the `annotations.title` field as a display name fallback, but the `ToolAnnotations` JSON schema does not formally define it._ {registry} validates and displays it for interoperability.

|`audience`
|array of strings
|Intended audience. The MCP spec defines a `Role` enum with values `"user"` and `"assistant"`. {registry} accepts any string values for forward compatibility with future spec revisions.

|`priority`
|number (0-1)
|Priority hint; higher values indicate higher priority
|===

.Example tool definition

[source,json]
----
{
  "name": "get_weather",
  "title": "Weather Information Provider",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or zip code"
      }
    },
    "required": ["location"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number",
        "description": "Temperature in celsius"
      },
      "conditions": {
        "type": "string",
        "description": "Weather conditions"
      }
    },
    "required": ["temperature", "conditions"]
  },
  "annotations": {
    "title": "Weather Lookup",
    "audience": ["user", "assistant"],
    "priority": 0.8
  }
}
----

// ref-mcp-well-known-endpoints
:_mod-docs-content-type: REFERENCE
[id="mcp-well-known-endpoints_{context}"]
== Well-known endpoints

[role="_abstract"]
You can search for and retrieve MCP tool definitions by using the following well-known endpoints.

.GET /.well-known/mcp-tools

Search for registered MCP tool definitions with filtering support.

.Query parameters
[cols="1,1,3"]
|===
|Parameter |Type |Description

|`name`
|string
|Filter by tool name (partial match)

|`parameter`
|string (repeatable)
|Filter by input parameter name

|`offset`
|integer
|Pagination offset (default: 0)

|`limit`
|integer
|Pagination limit (default: 20)
|===

.Example request
[source,bash]
----
curl "http://localhost:8080/.well-known/mcp-tools?parameter=location"
----

.Response: `McpToolSearchResults`

[source,json]
----
{
  "count": 1,
  "tools": [
    {
      "groupId": "mcp-tools",
      "artifactId": "weather-tool",
      "name": "get_weather",
      "title": "Weather Information Provider",
      "description": "Get current weather information",
      "owner": "admin",
      "createdOn": 1700000000000,
      "parameters": ["location"]
    }
  ]
}
----

.GET /.well-known/mcp-tools/{groupId}/{artifactId}

Retrieve a specific registered MCP tool definition.

.Path parameters
`groupId`:: The group containing the tool definition
`artifactId`:: The artifact ID of the tool definition

.Query parameters
`version` (optional):: Specific version (defaults to latest)

.Response
MCP tool definition JSON document

.GET /.well-known/schemas/mcp-tool/v1

Use this endpoint to retrieve the JSON Schema for MCP tool definitions. You can use the schema for IDE autocompletion and validation.

.Example
[source,bash]
----
curl "http://localhost:8080/.well-known/schemas/mcp-tool/v1"
----

// proc-creating-mcp-tool-artifact
:_mod-docs-content-type: PROCEDURE
[id="creating-mcp-tool-artifact_{context}"]
== Creating an MCP tool artifact

[role="_abstract"]
You can create an MCP tool artifact in {registry} by using the REST API.

.Prerequisites
* {registry} is installed and running.
* MCP tools support is enabled (`apicurio.mcp-tools.enabled=true` and `apicurio.features.experimental.enabled=true`).

.Procedure
* Send a `POST` request to the {registry} REST API to create the MCP tool artifact:
+
[source,bash]
----
curl -X POST "http://localhost:8080/apis/registry/v3/groups/mcp-tools/artifacts" \
  -H "Content-Type: application/json" \
  -d '{
    "artifactId": "weather-tool",
    "artifactType": "MCP_TOOL",
    "firstVersion": {
      "version": "1.0.0",
      "content": {
        "contentType": "application/json",
        "content": "{\"name\": \"get_weather\", \"title\": \"Weather Tool\", \"description\": \"Get weather data\", \"inputSchema\": {\"type\": \"object\", \"properties\": {\"location\": {\"type\": \"string\"}}, \"required\": [\"location\"]}}"
      }
    }
  }'
----

// ref-mcp-validation-rules
:_mod-docs-content-type: REFERENCE
[id="mcp-validation-rules_{context}"]
== Validation rules

[role="_abstract"]
{registry} validates MCP tool definitions at three levels.

[cols="1,3"]
|===
|Level |Description

|`NONE`
|No validation

|`SYNTAX_ONLY`
|Validates JSON syntax and that the document is a JSON object

|`FULL`
a|Complete validation including:

* Required `name` field (non-empty string)
* Required `inputSchema` field (object with `type` = `"object"` per spec docs guidance)
* Optional `title` and `description` must be strings if present
* Optional `outputSchema` must be an object if present
* Optional `annotations` validated as ToolAnnotations: `title` (string), `audience` (array of strings), `priority` (number 0-1). Note: `annotations.title` validation follows spec docs guidance; `audience` values are not restricted to the `Role` enum for forward compatibility.
|===

// ref-mcp-compatibility-checking
:_mod-docs-content-type: REFERENCE
[id="mcp-compatibility-checking_{context}"]
== Compatibility checking

[role="_abstract"]
When you version MCP tool definitions, {registry} checks for breaking changes based on compatibility rules.

.Compatible changes (allowed)
* Adding optional input parameters
* Changing name, title, or description
* Changing annotations
* Adding or modifying outputSchema

.Incompatible changes (might break clients)
* Removing input parameters from inputSchema.properties
* Adding new required parameters
* Removing required parameters
* Changing the inputSchema type

// ref-mcp-automatic-label-extraction
:_mod-docs-content-type: REFERENCE
[id="mcp-automatic-label-extraction_{context}"]
== Automatic label extraction

[role="_abstract"]
When you store MCP tool definitions, {registry} automatically extracts structured elements for search.

[cols="2,3"]
|===
|Element pattern |Source

|`mcp_tool:parameter:<name>`
|Each parameter name from inputSchema.properties
|===

You can use the extracted labels for efficient parameter-based discovery by using the {registry} search.

[role="_additional-resources"]
.Additional resources
* xref:getting-started/assembly-a2a-features.adoc[A2A Protocol Features]
* xref:getting-started/assembly-llm-artifact-types-implementation.adoc[LLM Artifact Types]
* link:https://modelcontextprotocol.io/specification/2025-11-25/server/tools[MCP Tools Specification]
* xref:getting-started/assembly-configuring-the-registry.adoc[Registry Configuration]
