JSON schemas

When you explicitly register agents or Model Context Protocol (MCP) servers with Agent Registry using the Services APIs, you must provide configuration files that describe their capabilities.

Agent Registry validates your uploaded files against external, open source specifications before indexing them to discover agent skills and tools.

This document provides examples and links to the expected JSON structures for Agent Cards and MCP tool specifications.

Agent Card schema

When registering an A2A-compliant agent, your agent-card.json payload must adhere to the official A2A specification. The skills array fields support the keyword search index.

{
  "name": "string",
  "description": "string",
  "version": "string",
  "protocolVersion": "string",
  "url": "string",
  "skills": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "tags": [
        "string"
      ],
      "examples": [
        "string"
      ]
    }
  ],
  "capabilities": {
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ]
}

Field definitions

  • name: The human-readable name of the agent.
  • description: A high-level summary of the agent's purpose.
  • version: The version of the agent, for example, 1.0.2.
  • protocolVersion: The version of the Agent2Agent protocol the agent implements, for example, 0.3.0.
  • url: The endpoint URL where the agent can be reached.
  • capabilities: Optional. An object specifying the agent's supported operational capabilities, such as streaming, pushNotifications, or stateTransitionHistory.
  • defaultInputModes: Optional. An array of strings defining the default MIME types the agent accepts as input, for example, ["text/plain"].
  • defaultOutputModes: Optional. An array of strings defining the default MIME types the agent produces as output, for example, ["text/plain"].

  • skills: An array of capabilities the agent possesses:

    • id: A unique programmatic identifier for the skill.
    • name: A human-readable name for the skill.
    • description: A detailed explanation of what the skill does.
    • tags: An array of keyword strings used to categorize the skill.
    • examples: An array of example prompts or scenarios this skill handles.

MCP tool schema

When registering an MCP server, your toolspec.json payload must include a list of tools that adhere to the MCP Tool object schema.

The expected payload is a JSON object with a single tools field, exactly as it is returned by the standard MCP tools or list request.

{
  "tools": [
    {
      "name": "string",
      "description": "string",
      "inputSchema": {
        "type": "object",
        "properties": {}
      },
      "annotations": {
        "title": "string",
        "readOnlyHint": false,
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true
      }
    }
  ]
}

Field definitions

  • tools: An array of tools provided by the server:

    • name: The programmatic identifier for the tool.
    • description: A human-readable explanation of the tool's purpose.
    • inputSchema: A JSON Schema object defining the expected parameters for the tool.

    • annotations: Behavioral hints that guide how orchestrator agents interact with the tool:

      • title: A human-readable title for the tool.
      • readOnlyHint: If true, the tool only retrieves data and doesn't modify its environment. Default is false.
      • destructiveHint: If true, the tool performs operations that might cause permanent changes. Default is true.
      • idempotentHint: If true, calling the tool repeatedly has no additional effect. Default is false.
      • openWorldHint: If true, the tool interacts with external systems. Default is true.