MCP server integration

You can connect Large Language Model (LLM) clients such as Claude Desktop to Apicurio Registry by using the Model Context Protocol (MCP) server. The MCP server is a lightweight adapter that uses stdio transport on the LLM client side and connects to Apicurio Registry over HTTP or HTTPS by using the REST API. You configure the target Apicurio Registry instance by setting the REGISTRY_URL environment variable. Through this adapter, you can manage groups, artifacts, versions, and configuration properties by using natural language.

MCP server overview

You can use the Apicurio Registry MCP server to interact with Apicurio Registry through the Model Context Protocol (MCP) from any LLM client. The MCP server acts as an adapter between two protocols: on the LLM client side, it communicates over stdio transport; on the Apicurio Registry side, it connects over HTTP or HTTPS by using the REST API. You configure the target Apicurio Registry instance by setting the REGISTRY_URL environment variable (or the registry.url Java system property).

When an LLM client sends a request, the MCP server converts that request into Apicurio Registry REST API calls, runs the operation, and returns the results to the LLM client. The LLM client prompts you for confirmation before each tool call.

The MCP server supports operations in the following categories:

  • System: Retrieve server information such as version and status

  • Groups: Create, list, search, and update artifact groups

  • Artifacts: Create, list, search, and update artifacts and metadata

  • Versions: Create, list, search, update content, and manage version state

  • Configuration: List, get, and update dynamic configuration properties

  • Prompt templates: List, get, and render prompt templates stored in Apicurio Registry

The MCP server has a safe mode that is enabled by default. Safe mode restricts operations that could cause unintended changes, such as limiting which configuration properties you can update.

Installing the MCP server

You can run the Apicurio Registry MCP server as a Docker container or build it from source. Both methods produce a server binary that LLM clients start on demand.

Prerequisites

  • Docker or Podman is installed, or Java 21 and Maven are installed for building from source.

  • A running Apicurio Registry instance is accessible at localhost:8080, or you set a custom URL by using the registry.url property.

All Docker commands in this guide also work with Podman. Substitute podman for docker if you use Podman as your container runtime.
Procedure

  1. Pull the MCP server Docker image:

    docker pull quay.io/apicurio/apicurio-registry-mcp-server:latest
    The latest tag refers to the most recent stable release. For development builds, use the latest-snapshot tag. For a specific version, use the version number as the tag, for example 3.2.4.

    Alternatively, to build the MCP server from source, clone the Apicurio Registry repository and run the following Maven command:

    mvn clean install -pl mcp -am -DskipTests

Configuring Claude Desktop for MCP

You can configure Claude Desktop to use the Apicurio Registry MCP server. After configuration, you interact with Apicurio Registry artifacts, groups, and versions by using natural language in Claude Desktop.

Prerequisites

  • Claude Desktop is installed.

  • A running Apicurio Registry instance is accessible at localhost:8080.

  • The Apicurio Registry MCP server Docker image is available, or you have built the MCP server JAR from source.

Procedure

  1. In Claude Desktop, navigate to File > Settings > Developer > Edit Config to open the MCP configuration file.

  2. Add the Apicurio Registry MCP server entry to the configuration file.

    If you are using the Docker image, add the following configuration:

    {
  "mcpServers": {
    "Apicurio Registry (docker)": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "REGISTRY_URL=<registry-url>",
        "quay.io/apicurio/apicurio-registry-mcp-server:latest"
      ]
    }
  }
}

    Replace <registry-url> with the URL of your Apicurio Registry instance, for example http://localhost:8080.

    If you built the MCP server from source, add the following configuration:

    {
  "mcpServers": {
    "Apicurio Registry (jar)": {
      "command": "java",
      "args": [
        "-jar",
        "<path-to-repo>/apicurio-registry/mcp/target/apicurio-registry-mcp-server-<version>-runner.jar"
      ]
    }
  }
}

    Replace <path-to-repo> with the absolute path to your local clone of the Apicurio Registry repository, and replace <version> with the version you built.

  3. Save the configuration file and restart Claude Desktop by selecting File > Exit and reopening the application.

Verification

  • Verify the connection by asking Claude a question about Apicurio Registry, for example:

    • "What is the version of the Registry server?"

    • "What groups are present in the Registry?"

    • "Create 10 example artifacts."

Available MCP tools

The Apicurio Registry MCP server provides the following tools for LLM clients to call. Claude Desktop prompts you for confirmation before each tool call.

Table 1. System tools
Tool name Description

get_server_info

Returns information about the Apicurio Registry server, including the version number.
Table 2. Group tools
Tool name Description

list_groups

Returns a list of artifact groups from Apicurio Registry. The result always contains the default group named default.

create_group

Creates a group in Apicurio Registry with an optional description and labels.

get_group_metadata

Returns metadata for a specific group.

update_group_metadata

Updates the description and labels for a group.

search_groups

Searches for groups by group ID, description, or labels.
Table 3. Artifact tools
Tool name Description

list_artifacts

Returns a list of artifacts within a group.

get_artifact_metadata

Returns metadata for a specific artifact within a group.

update_artifact_metadata

Updates the name, description, and labels for an artifact.

create_artifact

Creates an empty artifact in Apicurio Registry with optional name, description, type, and labels. Add content later by creating a version.

search_artifacts

Searches for artifacts by group ID, artifact ID, type, name, description, or labels.
Table 4. Version tools
Tool name Description

list_versions

Returns a list of versions within an artifact.

get_version_content

Returns the content of a specific artifact version, identified by a version expression.

get_version_metadata

Returns metadata for a specific artifact version.

create_version

Creates an artifact version with content. Supports draft mode for mutable versions.

update_version_state

Updates the state of an artifact version to ENABLED, DEPRECATED, DISABLED, or DRAFT.

update_version_metadata

Updates the name, description, and labels for an artifact version.

update_version_content

Updates the content of an artifact version that is in the DRAFT state.

search_versions

Searches for versions by group ID, artifact ID, type, name, description, or labels.
Table 5. Configuration tools
Tool name Description

get_artifact_types

Returns a list of artifact types supported by Apicurio Registry.

list_configuration_properties

Returns a list of all dynamic configuration properties that you can modify without restarting Apicurio Registry.

get_configuration_property

Returns information about a specific dynamic configuration property.

update_configuration_property

Updates a dynamic configuration property. In safe mode, you can update only the apicurio.rest.mutability.artifact-version-content.enabled property.
Table 6. Prompt template tools
Tool name Description

list_mcp_prompts

Lists all PROMPT_TEMPLATE artifacts that are MCP-enabled in Apicurio Registry.

get_mcp_prompt

Retrieves an MCP-enabled prompt template from Apicurio Registry and renders it with arguments that you provide.

render_prompt_template

Renders any PROMPT_TEMPLATE artifact with variables that you provide, regardless of MCP enablement.

You can also use the following MCP prompts in Claude Desktop by clicking the + icon and selecting Add from Apicurio Registry:

  • create_new_artifact_version: A guided workflow for creating artifact versions, including draft mode support and content iteration.

  • render_registry_prompt: Renders a prompt template from Apicurio Registry for interactive use.

MCP server configuration properties

You can configure the Apicurio Registry MCP server by using the following properties. Pass properties as Java system properties when you use the JAR, or as environment variables when you use Docker.

For the JAR method, place properties before the -jar argument:

java -Dregistry.url=myhost:8080 -jar apicurio-registry-mcp-server-*-runner.jar

For the Docker method, pass environment variables by using separate -e elements in the args array of the Claude Desktop configuration:

"args": [
  "run", "-i", "--rm",
  "-e", "REGISTRY_URL=myhost:8080",
  "quay.io/apicurio/apicurio-registry-mcp-server:latest"
]
Table 7. General properties
Property Environment variable Default Description

registry.url

REGISTRY_URL

localhost:8080

URL of the Apicurio Registry server that the MCP server connects to.

apicurio.mcp.safe-mode

APICURIO_MCP_SAFE_MODE

true

Restricts certain operations for safety. When enabled, you can update only allowlisted configuration properties.

apicurio.mcp.paging.limit

APICURIO_MCP_PAGING_LIMIT

200

Maximum number of items to return in a single paged result. Increase this value if Apicurio Registry contains a large number of objects.

apicurio.mcp.paging.limit-error

APICURIO_MCP_PAGING_LIMIT_ERROR

true

When the result count exceeds the paging limit, the operation fails. This property helps prevent inaccurate results when you count or list large datasets.
Table 8. Authentication properties
Property Environment variable Default Description

apicurio.mcp.auth.enabled

APICURIO_MCP_AUTH_ENABLED

false

When set to true, the MCP server uses OAuth2 client credentials authentication for connections to Apicurio Registry.

apicurio.mcp.auth.token-endpoint

APICURIO_MCP_AUTH_TOKEN_ENDPOINT

none

OAuth2 token endpoint URL. Required when authentication is enabled.

apicurio.mcp.auth.client-id

APICURIO_MCP_AUTH_CLIENT_ID

none

OAuth2 client ID. Required when authentication is enabled.

apicurio.mcp.auth.client-secret

APICURIO_MCP_AUTH_CLIENT_SECRET

none

OAuth2 client secret. Required when authentication is enabled.

apicurio.mcp.auth.scope

APICURIO_MCP_AUTH_SCOPE

none

OAuth2 scope. Optional.
Table 9. TLS properties
Property Environment variable Default Description

apicurio.mcp.tls.trust-all

APICURIO_MCP_TLS_TRUST_ALL

false

When set to true, all certificates are trusted. Use only in development environments.

apicurio.mcp.tls.verify-host

APICURIO_MCP_TLS_VERIFY_HOST

true

When set to true, the MCP server verifies the hostname in the server certificate.

apicurio.mcp.tls.truststore.type

APICURIO_MCP_TLS_TRUSTSTORE_TYPE

none

Trust store type: JKS, PKCS12, or PEM.

apicurio.mcp.tls.truststore.path

APICURIO_MCP_TLS_TRUSTSTORE_PATH

none

Path to the trust store file.

apicurio.mcp.tls.truststore.password

APICURIO_MCP_TLS_TRUSTSTORE_PASSWORD

none

Trust store password. Not required for PEM type.

apicurio.mcp.tls.keystore.type

APICURIO_MCP_TLS_KEYSTORE_TYPE

none

Key store type for mTLS client certificates: JKS or PKCS12.

apicurio.mcp.tls.keystore.path

APICURIO_MCP_TLS_KEYSTORE_PATH

none

Path to the key store file for mTLS.

apicurio.mcp.tls.keystore.password

APICURIO_MCP_TLS_KEYSTORE_PASSWORD

none

Key store password for mTLS.

Configuring MCP server authentication

You can configure the Apicurio Registry MCP server to authenticate with Apicurio Registry by using OAuth2 client credentials. You must configure authentication when Apicurio Registry is secured with an OIDC provider such as Keycloak.

Prerequisites

  • Apicurio Registry is configured with OIDC authentication.

  • An OAuth2 client is configured in your OIDC provider with client credentials grant type.

  • You know the token endpoint URL, client ID, and client secret.

Procedure

  1. Update the Claude Desktop MCP configuration to include OAuth2 credentials.

    If you are using the Docker image, add environment variables to the args array:

    {
  "mcpServers": {
    "Apicurio Registry (docker)": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "REGISTRY_URL=<registry-url>",
        "-e", "APICURIO_MCP_AUTH_ENABLED=true",
        "-e", "APICURIO_MCP_AUTH_TOKEN_ENDPOINT=http://localhost:8090/realms/registry/protocol/openid-connect/token",
        "-e", "APICURIO_MCP_AUTH_CLIENT_ID=registry-api",
        "-e", "APICURIO_MCP_AUTH_CLIENT_SECRET=<your-client-secret>",
        "quay.io/apicurio/apicurio-registry-mcp-server:latest"
      ]
    }
  }
}

    Replace <your-client-secret> with the client secret from your OIDC provider.

    If you built the MCP server from source, add system properties before the -jar argument:

    {
  "mcpServers": {
    "Apicurio Registry (jar)": {
      "command": "java",
      "args": [
        "-Dapicurio.mcp.auth.enabled=true",
        "-Dapicurio.mcp.auth.token-endpoint=http://localhost:8090/realms/registry/protocol/openid-connect/token",
        "-Dapicurio.mcp.auth.client-id=registry-api",
        "-Dapicurio.mcp.auth.client-secret=<your-client-secret>",
        "-jar",
        "<path-to-repo>/apicurio-registry/mcp/target/apicurio-registry-mcp-server-<version>-runner.jar"
      ]
    }
  }
}

    Replace <your-client-secret> with the client secret from your OIDC provider.

  2. Optional: Add the scope property if your OIDC provider requires a specific scope:

    • Docker: "-e", "APICURIO_MCP_AUTH_SCOPE=openid"

    • JAR: "-Dapicurio.mcp.auth.scope=openid"

  3. Restart Claude Desktop to apply the changes.

Configuring MCP server TLS

You can configure the Apicurio Registry MCP server to connect to Apicurio Registry over TLS. You configure trust store settings to verify the server certificate, and optionally configure key store settings for mutual TLS (mTLS) client certificate authentication.

Prerequisites

  • Apicurio Registry is configured with TLS.

  • You have the trust store file containing the CA certificate or server certificate.

  • For mTLS, you have a key store file containing the client certificate and private key.

Procedure

  1. Update the Claude Desktop MCP configuration to include TLS settings.

    If you are using the Docker image, add environment variables and mount the certificate files:

    {
  "mcpServers": {
    "Apicurio Registry (docker)": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/certs:/certs:ro",
        "-e", "REGISTRY_URL=https://registry.example.com:8443",
        "-e", "APICURIO_MCP_TLS_TRUSTSTORE_TYPE=PKCS12",
        "-e", "APICURIO_MCP_TLS_TRUSTSTORE_PATH=/certs/truststore.p12",
        "-e", "APICURIO_MCP_TLS_TRUSTSTORE_PASSWORD=<truststore-password>",
        "quay.io/apicurio/apicurio-registry-mcp-server:latest"
      ]
    }
  }
}

    If you built the MCP server from source, add system properties:

    {
  "mcpServers": {
    "Apicurio Registry (jar)": {
      "command": "java",
      "args": [
        "-Dregistry.url=https://registry.example.com:8443",
        "-Dapicurio.mcp.tls.truststore.type=PKCS12",
        "-Dapicurio.mcp.tls.truststore.path=/path/to/truststore.p12",
        "-Dapicurio.mcp.tls.truststore.password=<truststore-password>",
        "-jar",
        "<path-to-repo>/apicurio-registry/mcp/target/apicurio-registry-mcp-server-<version>-runner.jar"
      ]
    }
  }
}

  2. Optional: Add key store properties in addition to the trust store properties to configure mTLS with a client certificate:

    • Docker: add "-e", "APICURIO_MCP_TLS_KEYSTORE_TYPE=PKCS12", "-e", "APICURIO_MCP_TLS_KEYSTORE_PATH=/certs/keystore.p12", and "-e", "APICURIO_MCP_TLS_KEYSTORE_PASSWORD=<keystore-password>" to the args array.

    • JAR: add -Dapicurio.mcp.tls.keystore.type=PKCS12, -Dapicurio.mcp.tls.keystore.path=/path/to/keystore.p12, and -Dapicurio.mcp.tls.keystore.password=<keystore-password> before the -jar argument.

  3. Optional: In development environments, skip certificate verification by setting apicurio.mcp.tls.trust-all=true. Do not use this setting in production.

  4. Restart Claude Desktop to apply the changes.

MCP server troubleshooting

Use the following information to diagnose common issues with the Apicurio Registry MCP server.

Enabling detailed logging

By default, the MCP server does not write logs to a file. To enable file logging for troubleshooting, add logging properties to the Claude Desktop MCP configuration.

For the Docker image, add the following to the args array before the image name:

"-e", "QUARKUS_LOG_FILE_ENABLE=true",
"-e", "QUARKUS_LOG_FILE_PATH=/mnt/log/mcp-server.log",
"-v", "<path-to-log-dir>:/mnt/log",

For the JAR, add the following before the -jar argument:

"-Dquarkus.log.file.enable=true",
"-Dquarkus.log.file.path=<path-to-log-dir>/mcp-server.log",

Replace <path-to-log-dir> with the directory where you want to store the log file.

Table 10. Common issues
Issue Resolution

Claude Desktop does not show the Apicurio Registry MCP server tools.

Verify that the MCP configuration file is valid JSON. Restart Claude Desktop completely by selecting File > Exit and reopening the application.

The MCP server cannot connect to Apicurio Registry.

Verify that Apicurio Registry is running and accessible at the configured URL. Check the REGISTRY_URL environment variable or registry.url property. If you run the MCP server in Docker, ensure that REGISTRY_URL points to the correct host and port of your Apicurio Registry instance.

The paging limit error occurs when listing objects.

Apicurio Registry contains more objects than the configured paging limit. Increase the apicurio.mcp.paging.limit property, or set apicurio.mcp.paging.limit-error to false to allow partial results.

Authentication fails with OAuth2 credentials.

Verify that the token endpoint URL, client ID, and client secret are correct. Ensure that the OAuth2 client is configured for the client credentials grant type.

A configuration property update is rejected.

Safe mode restricts which configuration properties you can update. Set apicurio.mcp.safe-mode to false to allow all updates, or use the Apicurio Registry REST API directly.

Claude Desktop does not reflect changes to the MCP server code.

After you rebuild the MCP server, restart Claude Desktop completely by selecting File > Exit and reopening the application.
Additional resources