A2E Protocol

Specification

Version 0.1.0 - Complete A2E Protocol documentation

Abstract

The Agent-to-Entity Protocol (A2E) enables AI agents to discover how to interact with real-world entities. Entities publish a simple JSON file declaring which MCP endpoints serve them and what capabilities are available.

A2E is the missing link between AI agents and the physical world:

MCP defines how agents use tools
A2E defines how agents discover which MCPs serve a given entity

1. Introduction

1.1 Problem Statement

An AI agent receives: "Book a table at Acme Restaurant in Paris."

The agent needs to:

Identify "Acme Restaurant" as a restaurant in Paris
Discover which MCP endpoints can handle reservations for this entity
Connect to the appropriate MCP

Today, step 2 has no standard solution. MCP directories list servers by capabilities, not by entity. An agent knows booking-provider exists, but not that Acme Restaurant uses booking-provider.

A2E solves this by letting entities declare their MCP connections.

1.2 Design Goals

Simple: One JSON file, minimal required fields
Decentralized: Entities self-publish via well-known endpoints
Crawlable: Indexes can discover and aggregate entities
Intent-aware: Capabilities describe what actions are possible

1.3 Relationship to the MCP Ecosystem

┌──────────────────────────────────────────────────────────────┐
│                        AI Agent                               │
└──────────────────────┬───────────────────────────────────────┘
                       │
        ┌──────────────┴──────────────┐
        │                             │
        ▼                             ▼
┌───────────────────┐       ┌───────────────────┐
│   A2E (Discovery) │       │   MCP (Action)    │
│                   │       │                   │
│ "Which MCP serves │       │ "Execute this     │
│  this entity?"    │       │  tool on the MCP" │
└─────────┬─────────┘       └───────────────────┘
          │
          ▼
┌───────────────────┐
│      Entity       │
│  (restaurant,     │
│   airline, etc.)  │
└───────────────────┘

MCP Directories (Anthropic, OpenAI) list MCP servers by provider and capabilities:

"booking-provider is an MCP server with reservations capability"

A2E maps entities to their MCP connections:

"Acme Restaurant uses booking-provider for reservations"

These are complementary:

MCP Directory → "What MCPs exist?"
A2E → "Which MCP serves this specific entity?"

A2E inverts the model: instead of MCP providers submitting to centralized directories, entities declare their own connections. This is decentralized, scalable, and requires no gatekeeping.

1.4 Architecture Overview

End User          Client           AI Agent            A2E              MCP
    │               │                 │                 │                │
    │  "Book at     │                 │                 │                │
    │  Acme         │                 │                 │                │
    │  Restaurant"  │                 │                 │                │
    │──────────────►│                 │                 │                │
    │               │  User request   │                 │                │
    │               │────────────────►│                 │                │
    │               │                 │                 │                │
    │               │                 │  Resolve entity │                │
    │               │                 │────────────────►│                │
    │               │                 │                 │                │
    │               │                 │  MCP endpoint   │                │
    │               │                 │◄────────────────│                │
    │               │                 │                 │                │
    │               │                 │  Execute action │                │
    │               │                 │────────────────────────────────►│
    │               │                 │                 │                │
    │               │                 │  Confirmation   │                │
    │               │                 │◄────────────────────────────────│
    │               │  Response       │                 │                │
    │               │◄────────────────│                 │                │
    │  "Booked!"    │                 │                 │                │
    │◄──────────────│                 │                 │                │

Step	Component	Role
1	End User	Expresses intent in natural language
2	Client	Interface (Claude, ChatGPT, custom app)
3	AI Agent	Parses request, identifies entity and intent
4	A2E	Resolves which MCP serves the entity
5	MCP	Executes the action (reservation, order, etc.)

A2E handles step 4: the discovery layer between intent and action.

2. Well-Known Endpoint

Every entity MAY publish an A2E declaration at:

GET https://{domain}/.well-known/entity-card.json

Requirements:

MUST be served over HTTPS
MUST use Content-Type: application/json
MUST be publicly accessible (no authentication)

This follows the pattern of robots.txt, sitemap.xml, and security.txt.

3. Data Model

3.1 Document Structure

{
  "a2e": "0.1",
  "entity": { ... },
  "mcps": [ ... ]
}

Field	Type	Required	Description
`a2e`	string	Yes	Protocol version
`entity`	object	Yes	Entity metadata
`mcps`	array	Yes	MCP connections

3.2 Entity Object

{
  "entity": {
    "domain": "acme-restaurant.com",
    "name": "Acme Restaurant",
    "category": "restaurant",
    "description": "French bistro in Saint-Germain-des-Prés",
    "location": {
      "address": "11 Rue Saint-Benoît",
      "city": "Paris",
      "postal_code": "75006",
      "country": "FR",
      "lat": 48.8541,
      "lng": 2.3337
    },
    "contact": {
      "phone": "+33142612060",
      "email": "contact@acme-restaurant.com"
    }
  }
}

Required Fields

Field	Type	Description
`domain`	string	Primary domain (MUST match host)
`name`	string	Human-readable name
`category`	string	Primary category

Optional Fields

Field	Type	Description
`description`	string	Brief description (max 500 chars)
`location`	object	Physical location
`location.address`	string	Street address
`location.city`	string	City
`location.postal_code`	string	Postal/ZIP code
`location.country`	string	ISO 3166-1 alpha-2 country code
`location.lat`	number	Latitude
`location.lng`	number	Longitude
`contact`	object	Contact information
`contact.phone`	string	Phone number (E.164 format)
`contact.email`	string	Email address

Category	Description	Examples
`restaurant`	Food & beverage	Restaurants, cafes, bars
`beauty`	Personal care	Hair salons, spas, barbershops
`health`	Healthcare	Doctors, dentists, clinics
`hotel`	Accommodation	Hotels, B&Bs, vacation rentals
`transport`	Transportation	Airlines, trains, car rentals
`retail`	Shopping	Shops, stores, e-commerce
`entertainment`	Leisure	Cinemas, theaters, events
`fitness`	Sports & wellness	Gyms, yoga studios
`education`	Learning	Schools, tutoring, courses
`real_estate`	Property	Agencies, property management
`services`	Professional	SaaS, consulting, B2B
`other`	Other	Anything else

3.3 MCP Connection Object

{
  "mcps": [
    {
      "endpoint": "https://mcp.booking-provider.com",
      "capabilities": ["reservations", "availability", "menu"],
      "entity_ref": "rest-78432",
      "auth_required": true,
      "priority": 1
    },
    {
      "endpoint": "https://mcp.reviews-provider.com",
      "capabilities": ["reservations", "reviews"],
      "entity_ref": "12345",
      "auth_required": false,
      "priority": 2
    }
  ]
}

Required Fields

Field	Type	Description
`endpoint`	string	MCP server URL (HTTPS)
`capabilities`	array	List of supported capabilities

Optional Fields

Field	Type	Description
`entity_ref`	string	Entity's ID in the MCP provider's system. Allows agents to skip search calls.
`auth_required`	boolean	Whether user OAuth is required to perform actions. Defaults to `false`.
`priority`	integer	Preference order when multiple MCPs are available. Lower = preferred (1 = first choice).

3.4 Capabilities

Capabilities describe what an agent can do with an entity via an MCP. They enable intent matching: an agent looking to "book a table" can filter for entities with the reservations capability.

Standard Capabilities

Booking & Scheduling

Capability	Description
`reservations`	Book tables, rooms, appointments
`availability`	Check available slots
`booking_management`	Modify or cancel bookings
`waitlist`	Join a waitlist

Information

Capability	Description
`menu`	View menus, services, offerings
`pricing`	Get pricing information
`reviews`	Read or write reviews
`info`	General information queries

Communication

Capability	Description
`contact`	Send messages or inquiries
`support`	Customer support
`notifications`	Receive updates

Commerce

Capability	Description
`ordering`	Place orders
`payments`	Process payments
`loyalty`	Loyalty programs, rewards
`quotes`	Request quotes

Domain-Specific

Capability	Description
`check_in`	Check-in for flights, hotels
`seat_selection`	Select seats
`prescriptions`	Prescription management
`documents`	Document handling

Naming Guidelines

Capability names MUST follow these conventions:

Lowercase letters and underscores only (pattern: ^[a-z_]+$)
Use descriptive, action-oriented names
Prefer single words when possible (reservations, not make_reservations)
Use underscores for multi-word names (booking_management, seat_selection)

Implementations MAY define additional capabilities beyond the standard set.

4. Examples

4.1 Restaurant (Third-Party MCP)

{
  "a2e": "0.1",
  "entity": {
    "domain": "acme-restaurant.com",
    "name": "Acme Restaurant",
    "category": "restaurant",
    "description": "French bistro in Saint-Germain-des-Prés",
    "location": {
      "address": "11 Rue Saint-Benoît",
      "city": "Paris",
      "postal_code": "75006",
      "country": "FR",
      "lat": 48.8541,
      "lng": 2.3337
    }
  },
  "mcps": [
    {
      "endpoint": "https://mcp.booking-provider.com",
      "capabilities": ["reservations", "availability", "menu"],
      "entity_ref": "rest-78432",
      "auth_required": false,
      "priority": 1
    }
  ]
}

4.2 Airline (First-Party MCP)

{
  "a2e": "0.1",
  "entity": {
    "domain": "acme-airlines.com",
    "name": "Acme Airlines",
    "category": "transport",
    "location": {
      "city": "New York",
      "country": "US"
    }
  },
  "mcps": [
    {
      "endpoint": "https://mcp.acme-airlines.com",
      "capabilities": [
        "reservations",
        "availability",
        "check_in",
        "seat_selection",
        "booking_management",
        "loyalty"
      ],
      "auth_required": true
    }
  ]
}

4.3 Hotel (First-Party + Third-Party)

{
  "a2e": "0.1",
  "entity": {
    "domain": "grand-hotel.com",
    "name": "Grand Hotel",
    "category": "hotel"
  },
  "mcps": [
    {
      "endpoint": "https://mcp.grand-hotel.com",
      "capabilities": ["reservations", "availability", "loyalty", "check_in"],
      "auth_required": true,
      "priority": 1
    },
    {
      "endpoint": "https://mcp.hotel-ota.com",
      "capabilities": ["reservations", "availability", "reviews"],
      "entity_ref": "grand-hotel-123",
      "auth_required": false,
      "priority": 2
    }
  ]
}

4.4 E-commerce (Delegated Publishing)

E-commerce platforms can auto-generate A2E files for hosted stores (see Section 5):

{
  "a2e": "0.1",
  "entity": {
    "domain": "myboutique.ecommerce-platform.com",
    "name": "My Boutique",
    "category": "retail",
    "description": "Handmade jewelry and accessories"
  },
  "mcps": [
    {
      "endpoint": "https://mcp.ecommerce-platform.com",
      "capabilities": ["ordering", "availability", "info", "support"],
      "entity_ref": "myboutique"
    }
  ]
}

4.5 Minimal

{
  "a2e": "0.1",
  "entity": {
    "domain": "salon-marie.fr",
    "name": "Salon Marie",
    "category": "beauty"
  },
  "mcps": [
    {
      "endpoint": "https://mcp.appointments-provider.com",
      "capabilities": ["reservations", "availability"]
    }
  ]
}

5. Delegated Publishing

An MCP provider MAY publish A2E files on behalf of entities it hosts on subdomains.

Example: A booking provider hosts restaurant websites on *.booking-provider.com.

GET https://acme-restaurant.booking-provider.com/.well-known/entity-card.json

{
  "a2e": "0.1",
  "entity": {
    "domain": "acme-restaurant.booking-provider.com",
    "name": "Acme Restaurant",
    "category": "restaurant",
    "location": {
      "city": "Paris",
      "country": "FR"
    }
  },
  "mcps": [
    {
      "endpoint": "https://mcp.booking-provider.com",
      "capabilities": ["reservations", "availability", "menu"]
    }
  ]
}

The parent domain owner controls DNS for all subdomains and therefore has authority to publish on their behalf. Domain validation still applies: entity.domain MUST match the subdomain serving the file.

6. Security Considerations

6.1 Domain Validation

The entity.domain field MUST exactly match the host serving the file. This prevents impersonation.

✅ https://acme-restaurant.com/.well-known/entity-card.json
   → "domain": "acme-restaurant.com"

❌ https://evil.com/.well-known/entity-card.json
   → "domain": "acme-restaurant.com"  (rejected)

Crawlers and agents MUST reject files where domain does not match.

6.2 HTTPS Required

Both the .well-known endpoint and all MCP endpoints MUST use HTTPS.

6.3 No Authentication for Discovery

The .well-known/entity-card.json file MUST be publicly accessible. Authentication is handled at the MCP layer, not the discovery layer.

6.4 MCP Validation

The mcps array is a declaration of intent. Actual authorization is verified by the MCP endpoint when an agent connects. An entity claiming an MCP does not guarantee the MCP will accept requests for that entity.

7. Resolution

7.1 Direct Resolution

Agents MAY resolve entities directly:

1. Agent knows entity domain
2. Fetch https://{domain}/.well-known/entity-card.json
3. Parse mcps array
4. Connect to appropriate MCP based on capabilities

7.2 Indexed Resolution

Index: A service that crawls, aggregates, and provides search APIs for A2E declarations. Indexes enable agents to discover entities without knowing their domains in advance.

Indexed resolution flow:

1. Agent queries an index: "restaurants in Paris with reservations capability"
2. Index returns matching entities with their MCPs
3. Agent connects to MCP

7.3 Index Responsibilities

An index aggregates A2E declarations and provides fast resolution. The protocol defines the data format; indexes add value through aggregation, search, and trust signals.

Core functions (indexes MUST implement):

Function	Description
Crawling	Regularly fetch `.well-known/entity-card.json` from known domains
Validation	Verify domain matching, HTTPS, JSON schema
Search	Enable queries by name, location, category, capability
Caching	Serve cached data for performance

Optional functions (indexes MAY implement):

Function	Description
Trust scoring	Compute trust from domain age, SSL validity, crawl history
Abuse reporting	Accept and process user-reported issues
Blocklisting	Maintain lists of known malicious entities
Verification	Offer manual verification for entities
Deduplication	Merge entities across domains using heuristics

These trust mechanisms are implementation details of each index, not part of the A2E protocol. Different indexes MAY implement different trust models and compete on quality.

8. Scope and Non-Goals

8.1 What A2E Provides

A2E is a discovery protocol with built-in domain verification:

Discovery: Answers "which MCP serves this entity?"
Domain ownership verification: The well-known endpoint ensures only domain owners can publish A2E declarations for their domain (see Section 6.1)

8.2 What A2E Does NOT Address

Concern	Addressed by
MCP server trust and code signing	Sigstore, attestations, ToolHive
MCP authentication and authorization	OAuth 2.0, MCP spec
Agent-to-agent communication	A2A protocol (Google)
MCP capabilities and tool definitions	MCP spec
Payment processing	MCP implementation
Advanced entity verification	Index implementations (optional)

Indexes MAY implement additional verification layers beyond domain ownership, but these are not part of the A2E protocol.

Appendix A: JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["a2e", "entity", "mcps"],
  "properties": {
    "a2e": {
      "type": "string",
      "const": "0.1"
    },
    "entity": {
      "type": "object",
      "required": ["domain", "name", "category"],
      "properties": {
        "domain": { "type": "string" },
        "name": { "type": "string" },
        "category": {
          "type": "string",
          "enum": ["restaurant", "beauty", "health", "hotel", "transport", "retail", "entertainment", "fitness", "education", "real_estate", "services", "other"]
        },
        "description": { "type": "string", "maxLength": 500 },
        "location": {
          "type": "object",
          "properties": {
            "address": { "type": "string" },
            "city": { "type": "string" },
            "postal_code": { "type": "string" },
            "country": { "type": "string", "pattern": "^[A-Z]{2}$" },
            "lat": { "type": "number" },
            "lng": { "type": "number" }
          }
        },
        "contact": {
          "type": "object",
          "properties": {
            "phone": { "type": "string" },
            "email": { "type": "string", "format": "email" }
          }
        }
      }
    },
    "mcps": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["endpoint", "capabilities"],
        "properties": {
          "endpoint": { "type": "string", "format": "uri", "pattern": "^https://" },
          "capabilities": {
            "type": "array",
            "minItems": 1,
            "items": { "type": "string", "pattern": "^[a-z_]+$" }
          },
          "entity_ref": {
            "type": "string",
            "description": "Entity's ID in the MCP provider's system"
          },
          "auth_required": {
            "type": "boolean",
            "default": false,
            "description": "Whether user OAuth is required"
          },
          "priority": {
            "type": "integer",
            "minimum": 1,
            "description": "Preference order (1 = first choice)"
          }
        }
      }
    }
  }
}

Appendix B: Comparison with Related Standards

Standard	Purpose	Relationship to A2E
robots.txt	Crawler directives	A2E is for discovery, not access control
sitemap.xml	Page discovery for search engines	A2E is for MCP discovery for AI agents
Schema.org	Structured data for SEO	A2E is actionable, not just descriptive
MCP	Agent-tool interaction	A2E discovers which MCPs serve an entity
MCP Directory	Lists MCP servers by provider	A2E maps entities to MCPs
A2A	Agent-to-agent communication	A2E is agent-to-entity discovery

Appendix C: Changelog

0.1.0 (2025-12-20)

Initial public draft
Version corrected to follow semver conventions for early-stage specs
Entity-centric model
Capability-based intent matching
Delegated publishing for hosted entities
Index responsibilities and trust signals

Authors

A2E Protocol — https://a2e-protocol.org

License

This specification is released under CC-BY-4.0.

Source: GitHub - Auto-synced at build time

Specification

Abstract

1. Introduction

1.1 Problem Statement

1.2 Design Goals

1.3 Relationship to the MCP Ecosystem

1.4 Architecture Overview

2. Well-Known Endpoint

3. Data Model

3.1 Document Structure

3.2 Entity Object

Required Fields

Optional Fields

Categories

3.3 MCP Connection Object

Required Fields

Optional Fields

3.4 Capabilities

Standard Capabilities

Naming Guidelines

4. Examples

4.1 Restaurant (Third-Party MCP)

4.2 Airline (First-Party MCP)

4.3 Hotel (First-Party + Third-Party)

4.4 E-commerce (Delegated Publishing)

4.5 Minimal

5. Delegated Publishing

6. Security Considerations

6.1 Domain Validation

6.2 HTTPS Required

6.3 No Authentication for Discovery

6.4 MCP Validation

7. Resolution

7.1 Direct Resolution

7.2 Indexed Resolution

7.3 Index Responsibilities

8. Scope and Non-Goals

8.1 What A2E Provides

8.2 What A2E Does NOT Address

Appendix A: JSON Schema

Appendix B: Comparison with Related Standards

Appendix C: Changelog

0.1.0 (2025-12-20)

Authors

License