Entity Card

An Entity Card is a JSON file that declares which MCP providers can interact with your business. Version 0.2.0 introduces multi-entity support, allowing a single domain to define multiple entities.

File Location

Host your Entity Card at the well-known path:

https://example-restaurant.com/.well-known/entity-card.json

Schema

{
  "schema_version": "0.2.0",
  "domain": "example-restaurant.com",
  "entities": [
    {
      "name": "Acme Bistro",
      "path": "/",
      "location": {
        "city": "Paris",
        "country": "FR"
      },
      "mcps": [
        {
          "provider": "booking-provider",
          "endpoint": "https://mcp.booking-provider.com",
          "entity_id": "rest-123",
          "capabilities": ["reservations", "availability"],
          "priority": 10
        }
      ]
    }
  ]
}

Fields

Root Fields

Field	Type	Required	Description
schema_version	string	Yes	Must be "0.2.0"
domain	string	Yes	Your domain (must match where file is hosted)
entities	array	Yes	List of entities at this domain

Entity Object Fields

Field	Type	Required	Description
name	string	Yes	Display name of the entity
path	string	No	URL path for this entity (e.g., "/locations/downtown")
location	object	No	Physical location (city, country, coordinates)
mcps	array	Yes	List of MCP providers for this entity

MCP Object Fields

Field	Type	Required	Description
provider	string	Yes	Provider identifier
endpoint	string	Yes	MCP server URL
entity_id	string	No	Your ID at the provider
capabilities	string[]	No	What the MCP can do (e.g., reservations)
priority	number	No	Ordering hint (higher = preferred)

Multi-Entity Support

Version 0.2.0 allows you to define multiple entities under a single domain. This is useful for restaurant groups, hotel chains, or any business with multiple locations.

{
  "schema_version": "0.2.0",
  "domain": "acme-bistro-group.com",
  "entities": [
    {
      "name": "Acme Bistro Downtown",
      "path": "/locations/downtown",
      "location": {
        "city": "New York",
        "country": "US"
      },
      "mcps": [
        {
          "provider": "booking-provider",
          "endpoint": "https://mcp.booking-provider.com",
          "entity_id": "downtown-123",
          "capabilities": ["reservations"],
          "priority": 10
        }
      ]
    },
    {
      "name": "Acme Bistro Uptown",
      "path": "/locations/uptown",
      "location": {
        "city": "New York",
        "country": "US"
      },
      "mcps": [
        {
          "provider": "booking-provider",
          "endpoint": "https://mcp.booking-provider.com",
          "entity_id": "uptown-456",
          "capabilities": ["reservations"],
          "priority": 10
        }
      ]
    }
  ]
}

Each entity can have its own path to differentiate between locations, and its own set of MCP providers with unique entity_id values.

Verification

When your Entity Card is submitted to Dock AI, we verify that the domain field matches the domain where the file is hosted. This ensures you control the domain.

If an MCP provider has also registered your entity with a matching endpoint, your verification level is upgraded to Level 2 (dual attestation).

Priority Field

If you work with multiple MCP providers, use the priority field to indicate your preferred provider. Higher values indicate higher priority.

{
  "schema_version": "0.2.0",
  "domain": "example-restaurant.com",
  "entities": [
    {
      "name": "Example Restaurant",
      "path": "/",
      "mcps": [
        {
          "provider": "preferred-provider",
          "endpoint": "https://mcp.preferred-provider.com",
          "priority": 10
        },
        {
          "provider": "backup-provider",
          "endpoint": "https://mcp.backup-provider.com",
          "priority": 5
        }
      ]
    }
  ]
}

Note: Only entities can set priority. MCP providers cannot override this value during registration.

Next Steps

Once your Entity Card is hosted, submit your domain to index it in the registry.