A Well-Known URI Profile for Agent-Callable Commerce Endpoints

1.1. Motivating Flow

The profile exists to enable interactions of the following form. An end user asks a digital assistant: "find me a pair of size 10 running shoes under $20 near me, and order a pair if you find something in stock." A well-implemented assistant decomposes this into three steps:¶

1. Query a marketplace or registry of MCP servers that index commercial businesses, filtering by geographic proximity to the user, by industry classification (apparel, footwear), and by advertised capability (the ability to take an order programmatically).¶
2. For each candidate result, open the candidate's MCP server and use the standard MCP capability-listing methods (such as tools/list) to obtain the precise inventory and order-placement tools.¶
3. Identify a small number of viable candidates, surface them to the end user for confirmation, and place the order via the chosen server's MCP tools.¶

Without a shared vocabulary for business-level metadata, step 1 either fragments across vendor-specific directories or forces the assistant to open MCP sessions against every candidate to inspect tool descriptions, both of which are expensive and slow. This profile defines the shared vocabulary.¶

1.2. Relationship to Other Work

This profile depends on the Server Card schema defined by SEP-1649 [MCP-SERVER-CARDS] as a baseline. Where SEP-1649 specifies how an MCP client connects to a server (transport, identity of the server, MCP-level authorization), this profile does not re-specify those mechanisms. It only adds business-level information about the entity operating the server.¶

This profile is not a competitor to Schema.org's LocalBusiness vocabulary ([SCHEMA-ORG-LB]). Schema.org describes businesses for human-facing web pages. This profile describes businesses for agent-facing MCP discovery. Publishers may publish both; an optional field of this profile carries a Schema.org type for cross-referencing.¶

This profile is not a replacement for, nor a competitor to, the llms.txt convention (https://llmstxt.org). llms.txt is for passive LLM context; this profile is for active agent discovery and invocation. The two are complementary.¶

1.3. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.4. Terminology

Server Card

The discovery document retrieved from /.well-known/mcp.json, as defined by the core MCP specification (referenced here as [MCP-SERVER-CARDS]). The same document may also be served at /.well-known/mcp/server-card.json, the location proposed by [MCP-SERVER-CARDS-2127].¶

Commerce Profile (or "this profile")

The set of additional fields defined by this document, placed inside the Server Card's _meta object under the key com.beaconspec/commerce.¶

Marketplace (or Registry)

A service that indexes Server Cards from multiple commercial MCP servers and exposes a query interface to AI agents. A marketplace is consumed by AI clients; it is not part of the normative protocol defined here.¶

Profile Publisher

The party operating an MCP server who authors and publishes a Server Card carrying a Commerce Profile in its _meta object.¶

Origin

As defined in [RFC6454].¶

2.1. Location Within the Server Card

The Commerce Profile is carried within the Server Card's _meta object, the metadata extension mechanism defined by the MCP base specification [MCP-META]. The profile occupies a single member whose key is com.beaconspec/commerce.¶

This profile is independent of the path at which the Server Card is published. A Profile Publisher SHOULD serve the same Server Card document at both /.well-known/mcp.json (the canonical location) and /.well-known/mcp/server-card.json (the location proposed by [MCP-SERVER-CARDS-2127]), so that clients following either convention can discover it. Because the Commerce Profile travels inside the Server Card's _meta object, it is carried unchanged regardless of which path a client retrieves.¶

The key uses the reverse-DNS prefix form that MCP defines for _meta members. Per [MCP-META], only prefixes whose second label is modelcontextprotocol or mcp are reserved for the MCP project; com.beaconspec is controlled by Beacon Spec, so com.beaconspec/commerce is a conformant third-party key.¶

Implementations that do not understand the com.beaconspec/commerce member MUST ignore it, which is the default handling for unrecognized _meta members.¶

The value of the com.beaconspec/commerce member MUST be a JSON object. The object MUST conform to the schema defined in Section 3.¶

2.2. Profile Version

The version field within the commerce object carries the version of this Commerce Profile that the document conforms to. Versions follow Semantic Versioning 2.0.0 [SEMVER], formatted as the string "MAJOR.MINOR.PATCH". This document defines version "1.0.0".¶

Major-version increments indicate backward-incompatible schema changes. Minor-version increments indicate backward-compatible additions. Patch-version increments indicate editorial clarifications without schema change.¶

3.1. version (REQUIRED)

A string in Semantic Versioning 2.0.0 format. MUST equal "1.0.0" for documents conforming to this profile.¶

3.2. lastUpdated (REQUIRED)

An ISO 8601 timestamp ([RFC3339]) indicating when the commerce block was last modified. Marketplace implementations SHOULD use this field to skip re-indexing unchanged entries.¶

3.3. businessName (REQUIRED)

The business name as it should be displayed to end users. This may differ from the legal entity name. UTF-8 string, recommended maximum length 200 characters.¶

3.4. businessDescription (REQUIRED)

A short paragraph describing the business in plain language, for presentation to end users by AI agents. UTF-8 string, recommended maximum length 1000 characters.¶

3.5. endpoint (REQUIRED)

An object identifying the single hosted endpoint an AI client connects to, and the protocol spoken there. It has two members:¶

type (REQUIRED)

Either "mcp" (a Model Context Protocol server) or "api" (a plain HTTPS REST API described by an OpenAPI document). A commerce listing exposes exactly one hosted endpoint. The server self-describes its catalog on connection: for mcp, via the MCP initialize and tools/list exchange; for api, via its OpenAPI document.¶

url (REQUIRED)

A fully-qualified HTTPS URL for the endpoint. url MUST begin with https://.¶

A commerce listing addresses a live, hosted endpoint, not a package to be installed. Where the SEP-1649 Server Card already specifies an MCP endpoint for the same server, the values SHOULD be consistent.¶

3.6. naics (REQUIRED)

A non-empty array of strings. Each string is a NAICS 2022 industry classification code (the North American Industry Classification System, jointly maintained by the United States Census Bureau, Statistics Canada, and INEGI Mexico; see [NAICS]).¶

Real businesses commonly span multiple codes; the array shape is intentional. Codes MUST be six-digit strings. Numeric encoding is not permitted, because leading zeros are significant.¶

NAICS is North American by origin but widely used as a key in customer-relationship-management, sales, and business-to-business systems globally. International classification systems (ISIC, NACE) are out of scope for this version of the profile.¶

3.7. schemaOrgType (OPTIONAL)

A string equal to a Schema.org LocalBusiness subtype identifier (e.g., "Plumber", "HVACBusiness", "Restaurant"). Provided as a complement to NAICS for AI agents that consume Schema.org JSON-LD natively. See [SCHEMA-ORG-LB].¶

3.8. offeringType (REQUIRED)

A controlled-vocabulary string identifying what the business fundamentally offers. MUST be one of:¶

"product"

The business sells physical or digital goods.¶

"service"

The business performs work for a customer (including Software-as-a-Service).¶

"content"

The business produces or hosts informational content (news, reference, documentation, community).¶

"mixed"

The business combines two or more of the above as primary offerings.¶

3.9. locality (REQUIRED)

A controlled-vocabulary string identifying whether the business serves a defined geographic region or operates online without location dependence. MUST be one of:¶

"local"

Service or fulfillment is geographically bounded (e.g., a plumber, a restaurant). The geo field MUST be present.¶

"online-only"

The business operates without geographic constraint (e.g., a global SaaS). The geo field MAY be omitted.¶

"hybrid"

Both modes apply (e.g., a manufacturer that ships globally but also operates a flagship retail location). The geo field MUST be present.¶

3.10. geo (REQUIRED when locality is "local" or "hybrid")

An object with at minimum the following fields:¶

country (REQUIRED, string)

ISO 3166-1 alpha-2 country code (e.g., "US", "DE", "JP").¶

city (REQUIRED, string)

City name in UTF-8.¶

region (OPTIONAL, string)

State, province, or other first-level subdivision; ISO 3166-2 RECOMMENDED.¶

postalCode (OPTIONAL, string)

Postal or ZIP code as published locally.¶

3.11. capabilityTags (REQUIRED, possibly empty)

An array of capability identifiers advertising what the endpoint can do. These are not drawn from a fixed vocabulary. They are the function names discovered from the endpoint at ingestion time: the MCP tool names returned by tools/list for an mcp endpoint, or the operation identifiers in the OpenAPI document for an api endpoint. The full tool or operation definitions live in the Server Card itself; capabilityTags is the flat, filterable list a marketplace indexes.¶

The array MAY be empty (for example, before an endpoint has been probed). Entries MUST be unique. Account registration and authentication functions carry no special meaning here; registration and authentication are handled by the endpoint itself and are out of scope for this profile.¶

3.12. Other Optional Fields

contact

Object with optional email and phone string members. For human-escalation paths when an AI agent cannot resolve a transaction.¶

currency

ISO 4217 currency code (e.g., "USD"). Indicates the primary currency in which prices are quoted. Independent of geo.country (a US-based site may quote in "USD" while serving customers worldwide).¶

languages

Array of ISO 639-1 (or 639-3 where 639-1 does not exist) language codes that the MCP server's user-facing surfaces understand. Defaults to whatever the site's primary language is.¶

privacyPolicyUrl, termsOfServiceUrl

HTTPS URLs to the publisher's privacy policy and terms of service. AI agents acting on user behalf SHOULD surface these to end users before transacting.¶

displayName

Branding name to be used for display when it differs from businessName.¶

logoUrl

HTTPS URL to a square logo image suitable for AI client display. PNG or SVG RECOMMENDED.¶