MCP tool definition features in Apicurio Registry

You can store and manage MCP (Model Context Protocol) tool definitions as first-class artifacts in Apicurio Registry. You can use MCP tool features for central governance, version management, and discovery of MCP tools across your organization.

Overview

The 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.

Apicurio Registry provides a Tool Registry that stores MCP tool definitions with the following capabilities:

Storing an MCP_TOOL definition in Apicurio 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 Apicurio Registry MCP server. For more information, see 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.

Table 1. MCP tool registry endpoints and capabilities
Well-known endpoints Capabilities

  • /.well-known/mcp-tools (search tools)

  • /.well-known/mcp-tools/{groupId}/{artifactId} (retrieve tool)

  • Store tool definitions as MCP_TOOL artifacts

  • Search by name or input parameter

  • Version management

  • Validation and compatibility checking

Configuration

You can configure MCP tool features by using the following configuration properties.

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:

apicurio.features.experimental.enabled=true
apicurio.mcp-tools.enabled=true

MCP tool definition schema

Tool definitions follow the MCP specification (2025-11-25).

The MCP specification has two authoritative sources: the formal JSON schema and the specification docs. In some cases, these sources diverge. The following table notes where Apicurio Registry validation follows the spec docs guidance rather than the formal JSON schema.
Table 2. Tool fields
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:

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. Apicurio 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:

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. Apicurio 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". Apicurio 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
{
  "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
  }
}

Well-known endpoints

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.

Table 3. Query parameters
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
curl "http://localhost:8080/.well-known/mcp-tools?parameter=location"
Response: McpToolSearchResults
{
  "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
curl "http://localhost:8080/.well-known/schemas/mcp-tool/v1"

Creating an MCP tool artifact

You can create an MCP tool artifact in Apicurio Registry by using the REST API.

Prerequisites

  • Apicurio 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 Apicurio Registry REST API to create the MCP tool artifact:

    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\"]}}"
      }
    }
  }'

Validation rules

Apicurio Registry validates MCP tool definitions at three levels.

Level Description

NONE

No validation

SYNTAX_ONLY

Validates JSON syntax and that the document is a JSON object

FULL

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.

Compatibility checking

When you version MCP tool definitions, Apicurio 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

Automatic label extraction

When you store MCP tool definitions, Apicurio Registry automatically extracts structured elements for search.

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 Apicurio Registry search.

Additional resources