Agent registry quick start

You can use Apicurio Registry as a central registry for AI agents, prompt templates, and model schemas. You start Apicurio Registry with agent features enabled, register an agent card, discover agents by skill, and connect Claude Desktop to Apicurio Registry by using the Model Context Protocol (MCP).

Agent registry overview

Apicurio Registry functions as both an A2A (Agent-to-Agent) agent and an agent registry. As an A2A agent, Apicurio Registry exposes its own capabilities, such as schema validation, artifact management, and agent discovery. As an agent registry, Apicurio Registry stores and serves agent cards that other AI agents publish for discovery.

The A2A protocol is a standard that AI agents use to discover and communicate with each other through well-known endpoints. MCP (Model Context Protocol) is a standard that LLM-powered tools such as Claude Desktop use to interact with external services and data sources.

Apicurio Registry supports the following AI and ML artifact types:

  • AGENT_CARD: A2A agent card that describes an agent, its skills, and its capabilities

  • PROMPT_TEMPLATE: versioned prompt template with variable substitution for LLM interactions

  • MODEL_SCHEMA: input and output schema definition for an AI or ML model

  • MCP_TOOL: MCP tool definition that describes a tool, its input parameters, and its output schema

Starting Apicurio Registry with agent features

You can start Apicurio Registry with agent features enabled by using Docker Compose. Because A2A support is an experimental feature, you must enable the experimental features flag and the A2A flag.

Prerequisites

  • Docker and Docker Compose are installed

  • curl is installed

Procedure

  1. Create a docker-compose.yml file with the following content:

    version: '3.8'

services:
  apicurio-registry:
    image: quay.io/apicurio/apicurio-registry:latest
    container_name: agent-registry
    ports:
      - "8080:8080"
    environment:
      APICURIO_FEATURES_EXPERIMENTAL_ENABLED: "true"
      APICURIO_A2A_ENABLED: "true"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/health/live"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  apicurio-registry-ui:
    image: quay.io/apicurio/apicurio-registry-ui:latest
    container_name: agent-registry-ui
    ports:
      - "8888:8080"
    environment:
      REGISTRY_API_URL: "http://localhost:8080/apis/registry/v3"
    depends_on:
      apicurio-registry:
        condition: service_healthy
    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.

  2. Start the services:

    docker compose up -d

  3. Wait for the services to start.

Verification

  1. Verify that Apicurio Registry is running:

    curl http://localhost:8080/apis/registry/v3/system/info

  2. Verify that the A2A endpoint is active by retrieving the Apicurio Registry agent card:

    curl http://localhost:8080/.well-known/agent.json

    The response contains the agent card for the Apicurio Registry instance, including its built-in skills such as schema-validation, schema-search, artifact-management, compatibility-check, and agent-discovery.

Registering an agent card

You can register an agent card as an AGENT_CARD artifact in Apicurio Registry. After registration, other AI agents and orchestrators can discover the agent by using the well-known endpoints.

Prerequisites

  • Apicurio Registry is running with agent features enabled

Procedure

  1. Create a group to organize your agent cards:

    curl -X POST "http://localhost:8080/apis/registry/v3/groups" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": "ai-agents",
    "description": "AI agent cards"
  }'

  2. Register an agent card artifact in the group:

    curl -X POST "http://localhost:8080/apis/registry/v3/groups/ai-agents/artifacts" \
  -H "Content-Type: application/json" \
  -d '{
    "artifactId": "customer-support-agent",
    "artifactType": "AGENT_CARD",
    "firstVersion": {
      "version": "1.0.0",
      "content": {
        "contentType": "application/json",
        "content": "{\"name\": \"Customer Support Agent\", \"description\": \"Handles customer inquiries, analyzes sentiment, and generates responses\", \"version\": \"1.0.0\", \"supportedInterfaces\": [{\"url\": \"http://support-agent:9001\", \"protocolBinding\": \"http+json\", \"protocolVersion\": \"1.0\"}], \"provider\": {\"organization\": \"Acme Corp\", \"url\": \"https://acme.example.com\"}, \"skills\": [{\"id\": \"sentiment-analysis\", \"name\": \"Sentiment Analysis\", \"description\": \"Analyzes customer message sentiment\"}, {\"id\": \"response-generation\", \"name\": \"Response Generation\", \"description\": \"Generates context-aware customer responses\"}], \"capabilities\": {\"streaming\": false, \"pushNotifications\": false}, \"defaultInputModes\": [\"text\"], \"defaultOutputModes\": [\"text\"]}"
      }
    }
  }'
Verification

  1. Verify that the agent card is available through the well-known agents endpoint:

    curl http://localhost:8080/.well-known/agents

    The response includes the registered agent card with its skills and capabilities.

Discovering agents

You can discover registered agents by searching with query parameters such as agent name, skill ID, or capability. Apicurio Registry also exposes its own agent card at a dedicated well-known endpoint.

Prerequisites

  • Apicurio Registry is running with agent features enabled

  • At least one agent card is registered

Procedure

  1. Search for agents by name:

    curl "http://localhost:8080/.well-known/agents?name=Customer"

  2. Search for agents by skill ID:

    curl "http://localhost:8080/.well-known/agents?skill=sentiment-analysis"

  3. Retrieve a specific agent card by group and artifact ID:

    curl "http://localhost:8080/.well-known/agents/ai-agents/customer-support-agent"

  4. View the Apicurio Registry built-in agent card:

    curl http://localhost:8080/.well-known/agent.json

    You can also browse registered agent cards by using the Apicurio Registry web console at http://localhost:8888.

Connecting Claude Desktop by using MCP

You can connect Claude Desktop to Apicurio Registry by using the MCP server. After you configure Claude Desktop, you can interact with Apicurio Registry artifacts, search for schemas, and manage agent cards by using natural language.

Prerequisites

  • Apicurio Registry is running (on localhost:8080)

  • Claude Desktop is installed (macOS or Windows)

    Claude Desktop is officially supported on macOS and Windows. Linux support is available through community builds. For installation details, see the Claude Desktop download page.
Procedure

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

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

    {
  "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 local development with Docker Compose, use http://localhost:8080. For OpenShift deployments, use the route URL of your Apicurio Registry instance.

  3. Restart Claude Desktop by selecting File > Exit and reopening the application.

Verification

  1. Verify the connection by asking Claude a question about Apicurio Registry, for example: "What groups are present in Apicurio Registry?"

    The MCP server provides tools for working with groups, artifacts, versions, and configuration properties in Apicurio Registry.

Additional resources