{ "openrpc": "1.3.2", "info": { "title": "Universal Scheduling Protocol (USP) MCP API", "version": "2026-08-20", "description": "The Universal Scheduling Protocol (USP) MCP binding uses JSON-RPC 2.0 for AI agents that interact with USP via tool calls. MCP clients invoke USP operations via the standard MCP tools/call method, with params.name set to the method name defined here and params.arguments containing the operation parameters. Each method maps to a corresponding REST operation. Responses use the structuredContent/content dual-envelope pattern. Privileged vs public operation access follows specification.md Section 10.1.6 and mirrors openapi/usp-rest.json: public catalog/availability/registry-search methods MAY be anonymous; privileged methods (x-usp-access=privileged_platform|privileged_scoped) MUST authenticate with a mechanism declared in the business's AuthorizationPolicy (published top-level in a Standalone /.well-known/usp profile, or as config.authorization on the dev.usp-protocol.services binding in a UCP-Native /.well-known/ucp profile) and MUST bind to _meta.usp.profile. See components.x-usp-securitySchemes for the MCP expression of the documented mechanisms; that identifier set is open for forward compatibility with UCP, and unrecognized identifiers are ignored rather than treated as accepted.", "contact": { "url": "https://usp-protocol.dev" }, "license": { "name": "Apache-2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" } }, "servers": [ { "name": "default", "url": "https://business.example.com/usp/mcp" } ], "methods": [ { "name": "usp_services_list", "summary": "List Services", "description": "Returns a filtered, paginated list of services from the business catalog. Maps to POST /services/list. Public operation (Section 10.1.6): authentication optional; anonymous browse allowed.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": false, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPublic" } } }, "description": "MCP metadata. Public operation: authentication optional. _meta.usp.profile MAY be sent for capability negotiation (Standalone Mode)." }, { "name": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search query across service names, descriptions, and categories. When present, the business SHOULD rank results by relevance. Businesses that do not support search MUST ignore this field." }, { "name": "filters", "required": false, "schema": { "type": "object", "description": "Filter criteria to narrow results. All specified filters combine with AND logic.", "properties": { "type": { "type": "string", "description": "Service vertical to filter by." }, "category_id": { "type": "string", "description": "Single category ID. Shorthand for categories with one value. If both provided, categories takes precedence. Matches the primary categories[] entry's id, and MAY match any entry's id." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Category IDs to filter by (OR logic). Match rule: primary entry id, and MAY match any entry's id." }, "location_id": { "type": "string", "description": "Location ID to filter by." }, "price": { "type": "object", "description": "Price range filter in minor currency units.", "properties": { "min": { "type": "integer", "description": "Minimum price in minor currency units." }, "max": { "type": "integer", "description": "Maximum price in minor currency units." } } } } } }, { "name": "context", "required": false, "schema": { "type": "object", "description": "Buyer locale and intent signals for relevance, localization, and personalization. Aligns with UCP context pattern.", "properties": { "address_country": { "type": "string", "description": "Buyer's country (ISO 3166-1 alpha-2, e.g., US)." }, "address_region": { "type": "string", "description": "Region within the country (e.g., California)." }, "postal_code": { "type": "string", "description": "Postal code (e.g., 94043)." }, "coordinates": { "type": "object", "description": "Buyer's geographic coordinates for proximity-based ranking.", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90, "description": "Latitude in WGS 84 decimal degrees." }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "description": "Longitude in WGS 84 decimal degrees." } } }, "language": { "type": "string", "description": "Preferred language (IETF BCP 47, e.g., en, fr-CA)." }, "currency": { "type": "string", "description": "Preferred currency (ISO 4217, e.g., USD)." }, "intent": { "type": "string", "description": "Free-text buyer intent (e.g., 'looking for a relaxing spa treatment')." } }, "additionalProperties": true }, "description": "Buyer locale and intent signals. Businesses SHOULD use when available and MUST ignore unrecognized fields." }, { "name": "pagination", "required": false, "schema": { "type": "object", "properties": { "limit": { "type": "integer", "default": 20 }, "cursor": { "type": [ "string", "null" ] } } } } ], "result": { "name": "ListServicesResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "services", "pagination" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Optional errors, warnings, or informational messages about the response." } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "public" }, { "name": "usp_services_get", "summary": "Get Service", "description": "Returns the full service object for a single service. Maps to GET /services/{service_id}. Public operation (Section 10.1.6): authentication optional; anonymous browse allowed.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": false, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPublic" } } }, "description": "MCP metadata. Public operation: authentication optional. _meta.usp.profile MAY be sent for capability negotiation (Standalone Mode)." }, { "name": "service_id", "required": true, "schema": { "type": "string" } } ], "result": { "name": "GetServiceResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "service" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "service": { "$ref": "#/components/schemas/Service" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Optional errors, warnings, or informational messages about the service." } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "public" }, { "name": "usp_services_lookup", "summary": "Lookup Services", "description": "Returns full service objects for a batch of service IDs. Analogous to UCP catalog_lookup. Maps to POST /services/lookup. Public operation (Section 10.1.6): authentication optional; anonymous browse allowed.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": false, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPublic" } } }, "description": "MCP metadata. Public operation: authentication optional. _meta.usp.profile MAY be sent for capability negotiation (Standalone Mode)." }, { "name": "ids", "required": true, "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "description": "Service IDs to look up. Businesses MUST accept at least 50 IDs. Duplicates are silently deduplicated." }, { "name": "context", "required": false, "schema": { "type": "object", "description": "Buyer locale and intent signals for localization. Same definition as on usp_services_list.", "properties": { "address_country": { "type": "string", "description": "Buyer's country (ISO 3166-1 alpha-2)." }, "address_region": { "type": "string", "description": "Region within the country." }, "postal_code": { "type": "string", "description": "Postal code." }, "coordinates": { "type": "object", "description": "Buyer's geographic coordinates.", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 } } }, "language": { "type": "string", "description": "Preferred language (IETF BCP 47)." }, "currency": { "type": "string", "description": "Preferred currency (ISO 4217)." }, "intent": { "type": "string", "description": "Free-text buyer intent." } }, "additionalProperties": true }, "description": "Buyer locale and intent signals. Businesses MUST ignore unrecognized fields." } ], "result": { "name": "LookupServicesResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "services" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" }, "description": "Services matching the requested IDs. May contain fewer items than requested. Unordered." }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Errors, warnings, or informational messages about the lookup (e.g., service_not_found for unresolved IDs)." } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "public" }, { "name": "usp_services_feed", "summary": "Service Feed", "description": "Returns a paginated, chronologically ordered list of service records for incremental sync. Maps to GET /services/feed. Public operation (Section 10.1.6): authentication optional; anonymous browse allowed.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": false, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPublic" } } }, "description": "MCP metadata. Public operation: authentication optional. _meta.usp.profile MAY be sent for capability negotiation (Standalone Mode)." }, { "name": "cursor", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "required": false, "schema": { "type": "integer", "default": 50 } }, { "name": "location_id", "required": false, "schema": { "type": "string" } } ], "result": { "name": "ServiceFeedResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "items", "pagination", "feed_meta" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "items": { "type": "array", "items": { "type": "object" } }, "pagination": { "type": "object", "properties": { "cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for next request." }, "has_more": { "type": "boolean" } } }, "feed_meta": { "type": "object", "properties": { "feed_generated_at": {}, "total_services": {}, "feed_status": {} } }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Optional errors, warnings, or informational messages about the feed response." } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "public" }, { "name": "usp_services_feed_subscribe", "summary": "Create Feed Subscription", "description": "Register for push-based catalog change notifications. Maps to POST /services/feed/subscriptions. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy (http_message_signature recommended default; platform_key_pop for a permissionless caller proving possession of an ephemeral key it never transmits; oauth2_bearer / api_key / mtls when pre-established) and MUST include _meta.usp.profile bound to that credential.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatform" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6 / business AuthorizationPolicy (HTTP Authorization / Signature / mTLS on MCP-over-HTTP, and/or _meta.usp.authorization, which is also where a platform_key_pop proof rides on both MCP transports)." }, { "name": "callback_url", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "categories", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "events", "required": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "result": { "name": "FeedSubscriptionResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "subscription" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "subscription": { "$ref": "#/components/schemas/FeedSubscription" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" }, { "name": "usp_services_feed_subscription_get", "summary": "Get Feed Subscription", "description": "Returns the current state of a feed subscription. Maps to GET /services/feed/subscriptions/{subscription_id}. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy and MUST include _meta.usp.profile bound to that credential. A subscription MUST only be visible to the platform profile that created it.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatform" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED." }, { "name": "subscription_id", "required": true, "schema": { "type": "string" }, "description": "Identifier of the subscription to read." } ], "result": { "name": "FeedSubscriptionResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "subscription" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "subscription": { "$ref": "#/components/schemas/FeedSubscription" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" }, { "name": "usp_services_feed_unsubscribe", "summary": "Cancel Feed Subscription", "description": "Permanently cancels a feed subscription and stops delivery. Maps to DELETE /services/feed/subscriptions/{subscription_id}. Cancellation is terminal: a canceled subscription cannot be resumed, and the platform creates a new subscription instead. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy and MUST include _meta.usp.profile bound to that credential.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatform" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED." }, { "name": "subscription_id", "required": true, "schema": { "type": "string" }, "description": "Identifier of the subscription to cancel." } ], "result": { "name": "FeedSubscriptionResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "subscription" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "subscription": { "$ref": "#/components/schemas/FeedSubscription" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" }, { "name": "usp_services_feed_subscription_pause", "summary": "Pause Feed Subscription", "description": "Suspends delivery for a feed subscription without canceling it. Maps to POST /services/feed/subscriptions/{subscription_id}/pause. The subscription retains its cursor position so that resuming does not require a full resync. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy and MUST include _meta.usp.profile bound to that credential.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatform" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED." }, { "name": "subscription_id", "required": true, "schema": { "type": "string" }, "description": "Identifier of the subscription to pause." } ], "result": { "name": "FeedSubscriptionResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "subscription" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "subscription": { "$ref": "#/components/schemas/FeedSubscription" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" }, { "name": "usp_services_feed_subscription_resume", "summary": "Resume Feed Subscription", "description": "Resumes delivery for a paused feed subscription. Maps to POST /services/feed/subscriptions/{subscription_id}/resume. Delivery continues from the subscription's retained cursor position. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy and MUST include _meta.usp.profile bound to that credential.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatform" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED." }, { "name": "subscription_id", "required": true, "schema": { "type": "string" }, "description": "Identifier of the subscription to resume." } ], "result": { "name": "FeedSubscriptionResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "subscription" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "subscription": { "$ref": "#/components/schemas/FeedSubscription" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" }, { "name": "usp_availability_query", "summary": "Query Availability", "description": "Returns available time slots for a service within a date range. Maps to POST /availability/query. Platforms SHOULD query at most 7 calendar days per request. Businesses MAY reject wider ranges with error code range_too_wide. Slots are returned in ascending start order. Public operation (Section 10.1.6): authentication optional; anonymous browse allowed.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": false, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPublic" } } }, "description": "MCP metadata. Public operation: authentication optional. _meta.usp.profile MAY be sent for capability negotiation (Standalone Mode)." }, { "name": "service_id", "required": true, "schema": { "type": "string", "description": "The service to query." } }, { "name": "start_date", "required": true, "schema": { "type": "string", "description": "Start of range (RFC 3339 date or datetime)." } }, { "name": "end_date", "required": true, "schema": { "type": "string", "description": "End of range (RFC 3339 date or datetime)." } }, { "name": "timezone", "required": false, "schema": { "type": "string", "description": "IANA timezone. Defaults to business timezone." } }, { "name": "resource_id", "required": false, "schema": { "type": "string", "description": "Preferred resource. If provided, only slots where this resource is available are returned." } }, { "name": "party_size", "required": false, "schema": { "type": "integer", "default": 1, "description": "Number of participants. For group/reservation types, only slots with sufficient remaining capacity are returned." } }, { "name": "location_id", "required": false, "schema": { "type": "string", "description": "Location filter. Only slots at this location are returned. Applies to multi-location businesses." } }, { "name": "locale", "required": false, "schema": { "type": "string", "description": "BCP 47 language tag (e.g., en-US). When provided, the business SHOULD return human-readable content (resource names, slot labels, opening_hours day names) in the requested locale." } }, { "name": "cursor", "required": false, "schema": { "type": "string", "description": "Opaque pagination cursor from a previous response. Omit on the first request." } }, { "name": "limit", "required": false, "schema": { "type": "integer", "description": "Requested page size. Businesses MAY apply a lower or upper cap." } } ], "result": { "name": "QueryAvailabilityResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "service_id", "slots" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "service_id": { "type": "string" }, "slots": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSlot" } }, "opening_hours": { "type": "array", "description": "Regular business hours for the queried period. Special closures are reflected by the absence of slots, not by this field.", "items": { "type": "object", "required": [ "day_of_week", "opens", "closes" ], "properties": { "day_of_week": { "type": "array", "description": "Days this entry applies to. Lowercase English day names.", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] } }, "opens": { "type": "string", "description": "Opening time in HH:MM 24-hour format (local business time)." }, "closes": { "type": "string", "description": "Closing time in HH:MM 24-hour format (local business time). 00:00 or 24:00 indicates midnight (end of day)." } } } }, "messages": { "type": "array", "description": "Optional informational or warning messages about the result set.", "items": { "$ref": "#/components/schemas/Message" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "public" }, { "name": "usp_availability_hold", "summary": "Hold Slot", "description": "Creates a temporary hold on a time slot. Maps to POST /availability/holds. Requires the business to advertise holds: true in the dev.usp-protocol.services.availability capability. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy (http_message_signature recommended default; platform_key_pop for a permissionless caller proving possession of an ephemeral key it never transmits; oauth2_bearer / api_key / mtls when pre-established) and MUST include _meta.usp.profile bound to that credential.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatform" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6 / business AuthorizationPolicy (HTTP Authorization / Signature / mTLS on MCP-over-HTTP, and/or _meta.usp.authorization, which is also where a platform_key_pop proof rides on both MCP transports)." }, { "name": "slot_id", "required": true, "schema": { "type": "string" } }, { "name": "service_id", "required": true, "schema": { "type": "string" } }, { "name": "spots", "required": false, "schema": { "type": "integer", "default": 1 } } ], "result": { "name": "HoldSlotResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "hold": { "$ref": "#/components/schemas/Hold" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "booking_scoped_credential": { "$ref": "#/components/schemas/BookingScopedCredential", "description": "CONDITIONAL. Sender-constrained capability credential authorizing continuation operations on the resource just created. Returned on this creation result only, never on reads, and never as a member of the created resource object itself: it is a bearer secret with its own lifetime, and a platform that persists it into the resource it re-displays widens exactly the leak surface the cnf binding exists to close. Present when the business accepts the booking_scoped_credential mechanism. When the caller authenticated with platform_key_pop this carries cnf.jkt binding the credential to the key whose possession was proved on this call; the platform SHOULD verify cnf.jkt matches its own key, and MUST NOT treat a credential returned without cnf as sender-constrained." } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" }, { "name": "usp_availability_release", "summary": "Release Slot", "description": "Explicitly releases a hold. Maps to DELETE /availability/holds/{hold_id}. Requires the business to advertise holds: true in the dev.usp-protocol.services.availability capability. Privileged operation on an existing resource (Section 10.1.6): MUST authenticate as for privileged_platform, and SHOULD prefer a retained booking_scoped_credential when the business accepts that mechanism (see _meta.usp.authorization). When that credential was issued carrying cnf it is sender-constrained: a platform_key_pop proof bound to cnf.jkt is MANDATORY, and the business MUST reject the credential presented without one rather than accept it as a bearer token, whatever mechanism the caller declares.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedScoped" } } }, "description": "MCP metadata for a privileged scoped operation (existing booking, hold, waitlist entry, or registry registration). _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6; prefer booking_scoped_credential via _meta.usp.authorization when available, together with the platform_key_pop proof in _meta.usp.authorization.proof that its cnf binding requires." }, { "name": "hold_id", "required": true, "schema": { "type": "string" } } ], "result": { "name": "ReleaseSlotResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "hold" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "hold": { "$ref": "#/components/schemas/Hold" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_scoped" }, { "name": "usp_bookings_create", "summary": "Create Booking", "description": "Creates a new booking for a service at a specific time slot. Maps to POST /bookings. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy (http_message_signature recommended default; platform_key_pop for a permissionless caller proving possession of an ephemeral key it never transmits; oauth2_bearer / api_key / mtls when pre-established) and MUST include _meta.usp.profile bound to that credential.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatform" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6 / business AuthorizationPolicy (HTTP Authorization / Signature / mTLS on MCP-over-HTTP, and/or _meta.usp.authorization, which is also where a platform_key_pop proof rides on both MCP transports)." }, { "name": "service_id", "required": true, "schema": { "type": "string" } }, { "name": "slot_id", "required": true, "schema": { "type": "string" } }, { "name": "hold_id", "required": false, "schema": { "type": "string" } }, { "name": "buyer", "required": true, "schema": { "$ref": "#/components/schemas/Buyer" } }, { "name": "recipient", "required": false, "schema": { "$ref": "#/components/schemas/Buyer" }, "description": "The person receiving the service, when different from the buyer. When absent, the buyer is the recipient." }, { "name": "party_size", "required": false, "schema": { "type": "integer", "default": 1 } }, { "name": "resource_id", "required": false, "schema": { "type": "string" } }, { "name": "delivery_address", "required": false, "schema": { "$ref": "#/components/schemas/DeliveryAddress" }, "description": "The buyer's service delivery address. REQUIRED when the service's channel.type is at_buyer_location. Echoed back on the Booking object." }, { "name": "notes", "required": false, "schema": { "type": "string" } }, { "name": "post_payment_return_request", "required": false, "schema": { "$ref": "#/components/schemas/PostPaymentReturnRequest" }, "description": "Applicable when checkout_systems: redirect is in use. The platform SHOULD always include this field on the redirect checkout path — without it, the platform has no way to predict where the buyer will land after payment or cancellation/abandonment. If present, the business MUST redirect the buyer's browser (via GET) to the specified URL with the specified query parameters appended after payment completes, is cancelled, or is abandoned." } ], "result": { "name": "CreateBookingResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "booking" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "booking": { "$ref": "#/components/schemas/Booking" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "booking_scoped_credential": { "$ref": "#/components/schemas/BookingScopedCredential", "description": "CONDITIONAL. Sender-constrained capability credential authorizing continuation operations on the resource just created. Returned on this creation result only, never on reads, and never as a member of the created resource object itself: it is a bearer secret with its own lifetime, and a platform that persists it into the resource it re-displays widens exactly the leak surface the cnf binding exists to close. Present when the business accepts the booking_scoped_credential mechanism. When the caller authenticated with platform_key_pop this carries cnf.jkt binding the credential to the key whose possession was proved on this call; the platform SHOULD verify cnf.jkt matches its own key, and MUST NOT treat a credential returned without cnf as sender-constrained." } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" }, { "name": "usp_bookings_get", "summary": "Get Booking", "description": "Returns the current state of a booking. Maps to GET /bookings/{booking_id}. Privileged operation on an existing resource (Section 10.1.6): MUST authenticate as for privileged_platform, and SHOULD prefer a retained booking_scoped_credential when the business accepts that mechanism (see _meta.usp.authorization). When that credential was issued carrying cnf it is sender-constrained: a platform_key_pop proof bound to cnf.jkt is MANDATORY, and the business MUST reject the credential presented without one rather than accept it as a bearer token, whatever mechanism the caller declares.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedScopedNoIdempotency" } } }, "description": "MCP metadata for a privileged scoped operation (existing booking, hold, waitlist entry, or registry registration). _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6; prefer booking_scoped_credential via _meta.usp.authorization when available, together with the platform_key_pop proof in _meta.usp.authorization.proof that its cnf binding requires." }, { "name": "booking_id", "required": true, "schema": { "type": "string" } } ], "result": { "name": "GetBookingResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "booking" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "booking": { "$ref": "#/components/schemas/Booking" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_scoped" }, { "name": "usp_bookings_update", "summary": "Update Booking", "description": "Updates mutable fields (buyer, recipient, notes) on a booking. Maps to PUT /bookings/{booking_id}. Privileged operation on an existing resource (Section 10.1.6): MUST authenticate as for privileged_platform, and SHOULD prefer a retained booking_scoped_credential when the business accepts that mechanism (see _meta.usp.authorization). When that credential was issued carrying cnf it is sender-constrained: a platform_key_pop proof bound to cnf.jkt is MANDATORY, and the business MUST reject the credential presented without one rather than accept it as a bearer token, whatever mechanism the caller declares.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedScoped" } } }, "description": "MCP metadata for a privileged scoped operation (existing booking, hold, waitlist entry, or registry registration). _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6; prefer booking_scoped_credential via _meta.usp.authorization when available, together with the platform_key_pop proof in _meta.usp.authorization.proof that its cnf binding requires." }, { "name": "booking_id", "required": true, "schema": { "type": "string" } }, { "name": "buyer", "required": false, "schema": { "$ref": "#/components/schemas/Buyer" } }, { "name": "recipient", "required": false, "schema": { "$ref": "#/components/schemas/Buyer" }, "description": "The person receiving the service, when different from the buyer." }, { "name": "notes", "required": false, "schema": { "type": "string" } } ], "result": { "name": "UpdateBookingResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "booking" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "booking": { "$ref": "#/components/schemas/Booking" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_scoped" }, { "name": "usp_bookings_confirm", "summary": "Confirm Booking", "description": "Business-initiated confirmation for manual-mode bookings. Maps to POST /bookings/{booking_id}/confirm (specification.md Section 5.3.4). x-usp-access: business_only. Not a platform continuation method: a platform principal and a booking_scoped_credential MUST NOT authorize this call. Authentication of the business caller is deployment-defined. Auto-mode bookings that are not already confirmed MUST be rejected with invalid_transition at HTTP 200 in messages[].", "paramStructure": "by-name", "params": [ { "name": "booking_id", "required": true, "schema": { "type": "string" } } ], "result": { "name": "ConfirmBookingResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "booking" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "booking": { "$ref": "#/components/schemas/Booking" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "business_only" }, { "name": "usp_bookings_cancel", "summary": "Cancel Booking", "description": "Cancels a booking. Maps to POST /bookings/{booking_id}/cancel. Privileged operation on an existing resource (Section 10.1.6): MUST authenticate as for privileged_platform, and SHOULD prefer a retained booking_scoped_credential when the business accepts that mechanism (see _meta.usp.authorization). When that credential was issued carrying cnf it is sender-constrained: a platform_key_pop proof bound to cnf.jkt is MANDATORY, and the business MUST reject the credential presented without one rather than accept it as a bearer token, whatever mechanism the caller declares.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedScoped" } } }, "description": "MCP metadata for a privileged scoped operation (existing booking, hold, waitlist entry, or registry registration). _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6; prefer booking_scoped_credential via _meta.usp.authorization when available, together with the platform_key_pop proof in _meta.usp.authorization.proof that its cnf binding requires." }, { "name": "booking_id", "required": true, "schema": { "type": "string" } }, { "name": "reason", "required": false, "schema": { "type": "string" } } ], "result": { "name": "CancelBookingResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "booking" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "booking": { "$ref": "#/components/schemas/Booking" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_scoped" }, { "name": "usp_bookings_reschedule", "summary": "Reschedule Booking", "description": "Moves a booking to a different time slot. Maps to POST /bookings/{booking_id}/reschedule. Privileged operation on an existing resource (Section 10.1.6): MUST authenticate as for privileged_platform, and SHOULD prefer a retained booking_scoped_credential when the business accepts that mechanism (see _meta.usp.authorization). When that credential was issued carrying cnf it is sender-constrained: a platform_key_pop proof bound to cnf.jkt is MANDATORY, and the business MUST reject the credential presented without one rather than accept it as a bearer token, whatever mechanism the caller declares.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedScoped" } } }, "description": "MCP metadata for a privileged scoped operation (existing booking, hold, waitlist entry, or registry registration). _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6; prefer booking_scoped_credential via _meta.usp.authorization when available, together with the platform_key_pop proof in _meta.usp.authorization.proof that its cnf binding requires." }, { "name": "booking_id", "required": true, "schema": { "type": "string" } }, { "name": "slot_id", "required": true, "schema": { "type": "string" } }, { "name": "hold_id", "required": false, "schema": { "type": "string" }, "description": "Hold ID for the new slot. Present only when the business supports holds." } ], "result": { "name": "RescheduleBookingResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "booking" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "booking": { "$ref": "#/components/schemas/Booking" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_scoped" }, { "name": "usp_bookings_confirm_payment", "summary": "Confirm Payment", "description": "Callback after payment succeeds. Maps to POST /bookings/{booking_id}/confirm-payment. Privileged operation on an existing resource (Section 10.1.6): MUST authenticate as for privileged_platform, and SHOULD prefer a retained booking_scoped_credential when the business accepts that mechanism (see _meta.usp.authorization). When that credential was issued carrying cnf it is sender-constrained: a platform_key_pop proof bound to cnf.jkt is MANDATORY, and the business MUST reject the credential presented without one rather than accept it as a bearer token, whatever mechanism the caller declares.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedScoped" } } }, "description": "MCP metadata for a privileged scoped operation (existing booking, hold, waitlist entry, or registry registration). _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6; prefer booking_scoped_credential via _meta.usp.authorization when available, together with the platform_key_pop proof in _meta.usp.authorization.proof that its cnf binding requires." }, { "name": "booking_id", "required": true, "schema": { "type": "string" } }, { "name": "payment_result", "required": true, "schema": { "type": "object", "required": [ "status", "transaction_id", "amount_paid", "currency" ], "properties": { "status": { "type": "string", "enum": [ "paid", "deposit_paid" ] }, "provider": { "type": "string" }, "transaction_id": { "type": "string" }, "amount_paid": { "type": "integer" }, "currency": { "type": "string" }, "order_reference": { "type": "string" } } } } ], "result": { "name": "ConfirmPaymentResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "booking" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "booking": { "$ref": "#/components/schemas/Booking" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_scoped" }, { "name": "usp_waitlist_join", "summary": "Join Waitlist", "description": "Join the waitlist for a service/slot. Maps to POST /waitlist. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy (http_message_signature recommended default; platform_key_pop for a permissionless caller proving possession of an ephemeral key it never transmits; oauth2_bearer / api_key / mtls when pre-established) and MUST include _meta.usp.profile bound to that credential.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatform" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6 / business AuthorizationPolicy (HTTP Authorization / Signature / mTLS on MCP-over-HTTP, and/or _meta.usp.authorization, which is also where a platform_key_pop proof rides on both MCP transports)." }, { "name": "service_id", "required": true, "schema": { "type": "string" } }, { "name": "slot_id", "required": false, "schema": { "type": "string" } }, { "name": "buyer", "required": true, "schema": { "$ref": "#/components/schemas/Buyer" } }, { "name": "preferred_slots", "required": false, "schema": { "type": "array", "items": { "type": "object" } } } ], "result": { "name": "JoinWaitlistResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "entry" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "entry": { "$ref": "#/components/schemas/WaitlistEntry" }, "booking_scoped_credential": { "$ref": "#/components/schemas/BookingScopedCredential", "description": "CONDITIONAL. Sender-constrained capability credential authorizing continuation operations on the resource just created. Returned on this creation result only, never on reads, and never as a member of the created resource object itself: it is a bearer secret with its own lifetime, and a platform that persists it into the resource it re-displays widens exactly the leak surface the cnf binding exists to close. Present when the business accepts the booking_scoped_credential mechanism. When the caller authenticated with platform_key_pop this carries cnf.jkt binding the credential to the key whose possession was proved on this call; the platform SHOULD verify cnf.jkt matches its own key, and MUST NOT treat a credential returned without cnf as sender-constrained." } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" }, { "name": "usp_waitlist_list", "summary": "List Waitlist Entries", "description": "List waitlist entries with optional filtering by service and status. Maps to POST /waitlist/list. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy (http_message_signature recommended default; platform_key_pop for a permissionless caller proving possession of an ephemeral key it never transmits; oauth2_bearer / api_key / mtls when pre-established) and MUST include _meta.usp.profile bound to that credential.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatformNoIdempotency" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6 / business AuthorizationPolicy (HTTP Authorization / Signature / mTLS on MCP-over-HTTP, and/or _meta.usp.authorization, which is also where a platform_key_pop proof rides on both MCP transports)." }, { "name": "service_id", "required": false, "schema": { "type": "string" }, "description": "Filter entries by service. If omitted, entries for all services are returned." }, { "name": "status", "required": false, "schema": { "type": "string", "enum": [ "waiting", "offered", "accepted", "expired", "declined", "removed" ] }, "description": "Filter by waitlist status." }, { "name": "pagination", "required": false, "schema": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Cursor from a previous response for pagination." }, "limit": { "type": "integer", "minimum": 1, "description": "Maximum number of entries to return." } } } } ], "result": { "name": "ListWaitlistResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "entries" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/WaitlistEntry" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": "string", "description": "Cursor for the next page. Absent when no more results." }, "total": { "type": "integer", "description": "Total number of matching entries, if known." } } } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" }, { "name": "usp_waitlist_get", "summary": "Get Waitlist Entry", "description": "Get waitlist entry status. Maps to GET /waitlist/{entry_id}. Privileged operation on an existing resource (Section 10.1.6): MUST authenticate as for privileged_platform, and SHOULD prefer a retained booking_scoped_credential when the business accepts that mechanism (see _meta.usp.authorization). When that credential was issued carrying cnf it is sender-constrained: a platform_key_pop proof bound to cnf.jkt is MANDATORY, and the business MUST reject the credential presented without one rather than accept it as a bearer token, whatever mechanism the caller declares.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedScopedNoIdempotency" } } }, "description": "MCP metadata for a privileged scoped operation (existing booking, hold, waitlist entry, or registry registration). _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6; prefer booking_scoped_credential via _meta.usp.authorization when available, together with the platform_key_pop proof in _meta.usp.authorization.proof that its cnf binding requires." }, { "name": "entry_id", "required": true, "schema": { "type": "string" } } ], "result": { "name": "GetWaitlistEntryResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "entry" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "entry": { "$ref": "#/components/schemas/WaitlistEntry" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_scoped" }, { "name": "usp_waitlist_leave", "summary": "Leave Waitlist", "description": "Leave the waitlist. Maps to DELETE /waitlist/{entry_id}. Privileged operation on an existing resource (Section 10.1.6): MUST authenticate as for privileged_platform, and SHOULD prefer a retained booking_scoped_credential when the business accepts that mechanism (see _meta.usp.authorization). When that credential was issued carrying cnf it is sender-constrained: a platform_key_pop proof bound to cnf.jkt is MANDATORY, and the business MUST reject the credential presented without one rather than accept it as a bearer token, whatever mechanism the caller declares.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedScoped" } } }, "description": "MCP metadata for a privileged scoped operation (existing booking, hold, waitlist entry, or registry registration). _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6; prefer booking_scoped_credential via _meta.usp.authorization when available, together with the platform_key_pop proof in _meta.usp.authorization.proof that its cnf binding requires." }, { "name": "entry_id", "required": true, "schema": { "type": "string" } } ], "result": { "name": "LeaveWaitlistResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "entry": { "type": "object", "properties": { "id": {}, "status": { "enum": [ "removed" ] } } } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_scoped" }, { "name": "usp_waitlist_accept", "summary": "Accept Waitlist Offer", "description": "Accept an offered slot from the waitlist. Maps to POST /waitlist/{entry_id}/accept. Privileged operation on an existing resource (Section 10.1.6): MUST authenticate as for privileged_platform, and SHOULD prefer a retained booking_scoped_credential when the business accepts that mechanism (see _meta.usp.authorization). When that credential was issued carrying cnf it is sender-constrained: a platform_key_pop proof bound to cnf.jkt is MANDATORY, and the business MUST reject the credential presented without one rather than accept it as a bearer token, whatever mechanism the caller declares.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedScoped" } } }, "description": "MCP metadata for a privileged scoped operation (existing booking, hold, waitlist entry, or registry registration). _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6; prefer booking_scoped_credential via _meta.usp.authorization when available, together with the platform_key_pop proof in _meta.usp.authorization.proof that its cnf binding requires." }, { "name": "entry_id", "required": true, "schema": { "type": "string" } }, { "name": "hold_id", "required": false, "schema": { "type": "string" } } ], "result": { "name": "AcceptWaitlistOfferResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "entry": { "$ref": "#/components/schemas/WaitlistEntry" }, "booking": { "$ref": "#/components/schemas/Booking" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_scoped" }, { "name": "usp_waitlist_decline", "summary": "Decline Waitlist Offer", "description": "Decline an offered slot from the waitlist. Maps to POST /waitlist/{entry_id}/decline. Privileged operation on an existing resource (Section 10.1.6): MUST authenticate as for privileged_platform, and SHOULD prefer a retained booking_scoped_credential when the business accepts that mechanism (see _meta.usp.authorization). When that credential was issued carrying cnf it is sender-constrained: a platform_key_pop proof bound to cnf.jkt is MANDATORY, and the business MUST reject the credential presented without one rather than accept it as a bearer token, whatever mechanism the caller declares.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedScoped" } } }, "description": "MCP metadata for a privileged scoped operation (existing booking, hold, waitlist entry, or registry registration). _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6; prefer booking_scoped_credential via _meta.usp.authorization when available, together with the platform_key_pop proof in _meta.usp.authorization.proof that its cnf binding requires." }, { "name": "entry_id", "required": true, "schema": { "type": "string" } } ], "result": { "name": "DeclineWaitlistOfferResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "entry": { "$ref": "#/components/schemas/WaitlistEntry" } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_scoped" }, { "name": "usp_registry_register", "summary": "Register Business (Discovery Registry)", "description": "Register a USP-enabled business with an optional discovery registry. Maps to POST /registry/businesses. Requires dev.usp-protocol.discovery.registry. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy (http_message_signature recommended default; platform_key_pop for a permissionless caller proving possession of an ephemeral key it never transmits; oauth2_bearer / api_key / mtls when pre-established) and MUST include _meta.usp.profile bound to that credential.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatform" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6 / business AuthorizationPolicy (HTTP Authorization / Signature / mTLS on MCP-over-HTTP, and/or _meta.usp.authorization, which is also where a platform_key_pop proof rides on both MCP transports)." }, { "name": "profile_url", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "deployment_mode", "required": true, "schema": { "type": "string", "enum": [ "standalone", "ucp_native" ] } }, { "name": "name", "required": true, "schema": { "type": "string" } }, { "name": "description", "required": false, "schema": { "type": "string" } }, { "name": "verticals", "required": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "categories", "required": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "location", "required": false, "schema": { "$ref": "#/components/schemas/RegistryLocation" } }, { "name": "timezone", "required": true, "schema": { "type": "string" } } ], "result": { "name": "RegistryRegisterResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "registration" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "registration": { "$ref": "#/components/schemas/RegistryEntry" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" }, { "name": "usp_registry_search_business", "summary": "Search Businesses (Discovery Registry)", "description": "Search the discovery registry for businesses. Maps to POST /registry/search_business. Public operation (Section 10.1.6): authentication optional; anonymous browse allowed.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": false, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPublic" } } }, "description": "MCP metadata. Public operation: authentication optional. _meta.usp.profile MAY be sent for capability negotiation (Standalone Mode)." }, { "name": "location", "required": false, "schema": { "$ref": "#/components/schemas/RegistrySearchLocation" } }, { "name": "verticals", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "categories", "required": false, "schema": { "$ref": "#/components/schemas/RegistryCategoryIds" } }, { "name": "query", "required": false, "schema": { "type": "string" } }, { "name": "deployment_mode", "required": false, "schema": { "type": "string", "enum": [ "standalone", "ucp_native" ] } }, { "name": "context", "required": false, "schema": { "$ref": "#/components/schemas/RegistryContext" } }, { "name": "pagination", "required": false, "schema": { "$ref": "#/components/schemas/PaginationRequest" } } ], "result": { "name": "RegistrySearchBusinessResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "businesses", "pagination" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "businesses": { "type": "array", "items": { "$ref": "#/components/schemas/RegistryEntry" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "public" }, { "name": "usp_registry_search_services", "summary": "Search Services (Discovery Registry)", "description": "Search the discovery registry for services across businesses. Maps to POST /registry/search_services. Public operation (Section 10.1.6): authentication optional; anonymous browse allowed.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": false, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPublic" } } }, "description": "MCP metadata. Public operation: authentication optional. _meta.usp.profile MAY be sent for capability negotiation (Standalone Mode)." }, { "name": "location", "required": false, "schema": { "$ref": "#/components/schemas/RegistrySearchLocation" } }, { "name": "verticals", "required": false, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "categories", "required": false, "schema": { "$ref": "#/components/schemas/RegistryCategoryIds" } }, { "name": "query", "required": false, "schema": { "type": "string" } }, { "name": "price_range", "required": false, "schema": { "$ref": "#/components/schemas/RegistryPriceRangeFilter" } }, { "name": "duration_range", "required": false, "schema": { "$ref": "#/components/schemas/RegistryDurationRangeFilter" } }, { "name": "desired_service_time_ranges", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DesiredServiceTimePreference" } }, "description": "Optional buyer time preferences for availability ranking. Ranking context only; not a hard filter." }, { "name": "prefer_sooner_availability_slots", "required": false, "schema": { "type": "boolean", "default": true }, "description": "When false, registry default ordering ignores soonness within the availability signal." }, { "name": "context", "required": false, "schema": { "$ref": "#/components/schemas/RegistryContext" } }, { "name": "pagination", "required": false, "schema": { "$ref": "#/components/schemas/PaginationRequest" } } ], "result": { "name": "RegistrySearchServicesResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "services", "pagination" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/RegistryServiceSearchResult" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "public" }, { "name": "usp_registry_get", "summary": "Get Registration (Discovery Registry)", "description": "Get a business registration by ID. Maps to GET /registry/businesses/{id}. Public operation (Section 10.1.6): authentication optional; anonymous browse allowed.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": false, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPublic" } } }, "description": "MCP metadata. Public operation: authentication optional. _meta.usp.profile MAY be sent for capability negotiation (Standalone Mode)." }, { "name": "id", "required": true, "schema": { "type": "string" } } ], "result": { "name": "RegistryGetResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "registration" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "registration": { "$ref": "#/components/schemas/RegistryEntry" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "public" }, { "name": "usp_registry_update", "summary": "Update Registration (Discovery Registry)", "description": "Update an existing registry registration. Maps to PUT /registry/businesses/{id}. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy (http_message_signature recommended default; platform_key_pop for a permissionless caller proving possession of an ephemeral key it never transmits; oauth2_bearer / api_key / mtls when pre-established) and MUST include _meta.usp.profile bound to that credential.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatform" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6 / business AuthorizationPolicy (HTTP Authorization / Signature / mTLS on MCP-over-HTTP, and/or _meta.usp.authorization, which is also where a platform_key_pop proof rides on both MCP transports)." }, { "name": "id", "required": true, "schema": { "type": "string" } }, { "name": "profile_url", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "deployment_mode", "required": true, "schema": { "type": "string", "enum": [ "standalone", "ucp_native" ] } }, { "name": "name", "required": true, "schema": { "type": "string" } }, { "name": "description", "required": false, "schema": { "type": "string" } }, { "name": "verticals", "required": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "categories", "required": true, "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "location", "required": false, "schema": { "$ref": "#/components/schemas/RegistryLocation" } }, { "name": "timezone", "required": true, "schema": { "type": "string" } } ], "result": { "name": "RegistryUpdateResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "required": [ "usp", "registration" ], "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" }, "registration": { "$ref": "#/components/schemas/RegistryEntry" }, "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" }, { "name": "usp_registry_delete", "summary": "Delete Registration (Discovery Registry)", "description": "Remove a business from the discovery registry. Maps to DELETE /registry/businesses/{id}. Privileged operation (Section 10.1.6, platform-level): MUST authenticate with a mechanism from the business AuthorizationPolicy (http_message_signature recommended default; platform_key_pop for a permissionless caller proving possession of an ephemeral key it never transmits; oauth2_bearer / api_key / mtls when pre-established) and MUST include _meta.usp.profile bound to that credential.", "paramStructure": "by-name", "params": [ { "name": "_meta", "required": true, "schema": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/McpUspMetaPrivilegedPlatform" } } }, "description": "MCP metadata for a privileged platform-level operation. _meta.usp.profile is REQUIRED. Authenticate per Section 10.1.6 / business AuthorizationPolicy (HTTP Authorization / Signature / mTLS on MCP-over-HTTP, and/or _meta.usp.authorization, which is also where a platform_key_pop proof rides on both MCP transports)." }, { "name": "id", "required": true, "schema": { "type": "string" } } ], "result": { "name": "RegistryDeleteResult", "schema": { "type": "object", "required": [ "structuredContent" ], "properties": { "structuredContent": { "type": "object", "properties": { "usp": { "$ref": "#/components/schemas/USPMeta" } }, "description": "Empty or usp-only success payload (HTTP 204 has no body in REST)." }, "content": { "type": "array", "description": "Human-readable text summary for MCP clients that render text.", "items": { "type": "object", "required": [ "type", "text" ], "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } } }, "errors": [ { "$ref": "#/components/errors/USPProtocolError" } ], "x-usp-access": "privileged_platform" } ], "components": { "schemas": { "BookingScopedCredential": { "$ref": "https://usp-protocol.dev/schemas/profile.json#/$defs/BookingScopedCredential" }, "ConfirmationKey": { "$ref": "https://usp-protocol.dev/schemas/usp.json#/$defs/ConfirmationKey" }, "PopProofJwt": { "$ref": "https://usp-protocol.dev/schemas/usp.json#/$defs/PopProofJwt" }, "BookingWebhookEvent": { "$ref": "https://usp-protocol.dev/schemas/services/webhook_event.json#/$defs/BookingEvent" }, "CatalogWebhookEvent": { "$ref": "https://usp-protocol.dev/schemas/services/webhook_event.json#/$defs/CatalogEvent" }, "WaitlistWebhookEvent": { "$ref": "https://usp-protocol.dev/schemas/services/webhook_event.json#/$defs/WaitlistEvent" }, "RegistryContext": { "$ref": "https://usp-protocol.dev/schemas/services/registry.json#/$defs/RegistryContext" }, "RegistryCategoryIds": { "$ref": "https://usp-protocol.dev/schemas/services/registry.json#/$defs/RegistryCategoryIds" }, "RegistryLocation": { "$ref": "https://usp-protocol.dev/schemas/services/registry.json#/$defs/RegistryLocation" }, "RegistrySearchLocation": { "$ref": "https://usp-protocol.dev/schemas/services/registry.json#/$defs/RegistrySearchLocation" }, "RegistryPriceRangeFilter": { "$ref": "https://usp-protocol.dev/schemas/services/registry.json#/$defs/PriceRangeFilter" }, "RegistryDurationRangeFilter": { "$ref": "https://usp-protocol.dev/schemas/services/registry.json#/$defs/DurationRangeFilter" }, "DesiredServiceTimePreference": { "$ref": "https://usp-protocol.dev/schemas/services/registry.json#/$defs/DesiredServiceTimePreference" }, "RankSignals": { "$ref": "https://usp-protocol.dev/schemas/services/registry.json#/$defs/RankSignals" }, "RegistryEntry": { "$ref": "https://usp-protocol.dev/schemas/services/registry.json#/$defs/RegistryEntry" }, "RegistryServiceSearchResult": { "$ref": "https://usp-protocol.dev/schemas/services/registry.json#/$defs/ServiceSearchResult" }, "PaginationRequest": { "$ref": "https://usp-protocol.dev/schemas/usp.json#/$defs/PaginationRequest" }, "Pagination": { "$ref": "https://usp-protocol.dev/schemas/usp.json#/$defs/Pagination" }, "USPMeta": { "$ref": "https://usp-protocol.dev/schemas/usp.json#/$defs/response_schema" }, "Service": { "$ref": "https://usp-protocol.dev/schemas/services/catalog.json#/$defs/Service" }, "FeedSubscription": { "$ref": "https://usp-protocol.dev/schemas/rest_common.json#/$defs/FeedSubscription" }, "TimeSlot": { "$ref": "https://usp-protocol.dev/schemas/services/availability.json#/$defs/TimeSlot" }, "Hold": { "$ref": "https://usp-protocol.dev/schemas/services/availability.json#/$defs/Hold" }, "Buyer": { "$ref": "https://usp-protocol.dev/schemas/services/booking.json#/$defs/Buyer" }, "BuyerConsent": { "$ref": "https://usp-protocol.dev/schemas/services/booking.json#/$defs/BuyerConsent" }, "DeliveryAddress": { "$ref": "https://usp-protocol.dev/schemas/services/booking.json#/$defs/DeliveryAddress" }, "Booking": { "$ref": "https://usp-protocol.dev/schemas/services/booking.json#/$defs/Booking" }, "BookingPayment": { "$ref": "https://usp-protocol.dev/schemas/services/booking.json#/$defs/BookingPayment" }, "PaymentContext": { "$ref": "https://usp-protocol.dev/schemas/services/booking.json#/$defs/PaymentContext" }, "Action": { "$ref": "https://usp-protocol.dev/schemas/services/booking.json#/$defs/Action" }, "Message": { "$ref": "https://usp-protocol.dev/schemas/services/booking.json#/$defs/Message" }, "Dispute": { "$ref": "https://usp-protocol.dev/schemas/services/booking.json#/$defs/Dispute" }, "PostPaymentReturnRequest": { "$ref": "https://usp-protocol.dev/schemas/services/booking.json#/$defs/PostPaymentReturnRequest" }, "WaitlistEntry": { "$ref": "https://usp-protocol.dev/schemas/services/waitlist.json#/$defs/WaitlistEntry" }, "CapabilityEntry": { "$ref": "https://usp-protocol.dev/schemas/usp.json#/$defs/CapabilityEntry" }, "ProfileCapabilityEntry": { "$ref": "https://usp-protocol.dev/schemas/usp.json#/$defs/ProfileCapabilityEntry" }, "McpAuthorization": { "type": "object", "title": "McpAuthorization", "description": "MCP-carried authentication for privileged operations per specification.md Section 10.1.6. When MCP runs over HTTP, prefer presenting oauth2_bearer / api_key on the HTTP Authorization header, http_message_signature via RFC 9421 Signature headers, and mtls via the TLS client certificate; in those cases omit this object or set mechanism to match the transport credential. Use this object when the credential must ride inside the tool call (stdio MCP, or a booking_scoped_credential that is not an HTTP Authorization header). MUST NOT carry a Link wallet token. Mechanism values come from the same open AuthorizationMechanism identifier set used by AuthorizationPolicy and by openapi/usp-rest.json securitySchemes; a business that receives an identifier it does not recognize MUST reject the call as unauthenticated rather than treat the unknown mechanism as accepted.", "required": [ "mechanism" ], "properties": { "mechanism": { "$ref": "https://usp-protocol.dev/schemas/profile.json#/$defs/AuthorizationMechanism", "description": "Which accepted mechanism authenticates this privileged call." }, "credential": { "type": "string", "description": "REQUIRED when mechanism is oauth2_bearer, api_key, or booking_scoped_credential and the credential is not already presented on the MCP HTTP transport. Omit when mechanism is http_message_signature or mtls (those bind at the HTTP/TLS layer of an MCP-over-HTTP session). For platform_key_pop the rule depends on the tier: OMIT at issuance, where no credential exists yet and the proof alone authenticates the caller, and REQUIRED at presentation on a privileged_scoped method, where it carries the booking_scoped_credential value that the accompanying proof's ath claim covers." }, "proof": { "$ref": "https://usp-protocol.dev/schemas/usp.json#/$defs/PopProofJwt", "description": "Proof of possession for the platform_key_pop mechanism, carried here on BOTH MCP transports - stdio and HTTP-SSE. MCP-over-HTTP deliberately does not use a REST-style DPoP header, so there is one client code path and a business behind an SSE gateway need not know its own externally visible URL to verify a proof. REQUIRED when mechanism is platform_key_pop. ALSO REQUIRED, whatever mechanism is declared, when the presented credential was issued carrying cnf: such a credential is sender-constrained, and a business MUST reject it presented without a matching proof rather than accept it as a bearer token. That rule is what stops the mechanism being bypassed by declaring mechanism=booking_scoped_credential and omitting this field - mechanism is caller-asserted and, like the rest of this object, is excluded from the usp_p digest. Header is typ usp-pop+jwt (deliberately not dpop+jwt, so a REST proof and an MCP proof cannot be replayed as one another), alg EdDSA, jwk the bare public key. Claims are usp_m (the invoked method name), aud (a business profile URI the callee publishes), usp_p (base64url SHA-256 over the JCS canonicalization of params with _meta.usp.authorization removed), iat, jti, ath at presentation only, and nonce only after a challenge. See specification.md Section 9.2.2." } }, "additionalProperties": false }, "McpUspMetaPublic": { "type": "object", "required": [], "description": "USP protocol metadata for this MCP tool call. Public operation: authentication is optional; profile MAY still be sent for capability negotiation.", "properties": { "profile": { "type": "string", "format": "uri", "description": "Platform profile URI for capability negotiation and identity binding (MCP equivalent of the REST USP-Agent / UCP-Agent header). REQUIRED on privileged operations. The business fetches this URI over HTTPS with no redirects and caches by URI (minimum 60s TTL floor). See specification.md Sections 8.2.2 and 10.1.6." }, "correlation_id": { "type": "string", "description": "OPTIONAL non-normative money-path correlation join id (specification.md Section 9.7). Opaque, non-PII token; equivalent to the REST USP-Correlation-Id header. Recipients that do not participate ignore this field without failing the request. Not a substitute for booking_id or payment identifiers." } }, "additionalProperties": false }, "McpUspMetaPrivilegedPlatform": { "type": "object", "required": [ "profile" ], "description": "USP protocol metadata for this MCP tool call. Privileged operation: profile is REQUIRED and authentication MUST satisfy Section 10.1.6. Platform-level privileged call (create booking/hold/waitlist, register, subscribe): accepts http_message_signature, platform_key_pop, oauth2_bearer, api_key, or mtls from AuthorizationPolicy. booking_scoped_credential does not apply at this tier, because no booking or waitlist entry exists yet - this is the tier at which one is ISSUED. A caller using platform_key_pop here sends authorization.proof with NO credential and the proof carries no ath; the business computes the RFC 7638 thumbprint of the proof header jwk, records it as the platform identity, and binds the credential it issues to that key.", "properties": { "profile": { "type": "string", "format": "uri", "description": "Platform profile URI for capability negotiation and identity binding (MCP equivalent of the REST USP-Agent / UCP-Agent header). REQUIRED on privileged operations. The business fetches this URI over HTTPS with no redirects and caches by URI (minimum 60s TTL floor). See specification.md Sections 8.2.2 and 10.1.6." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Idempotency key for state-modifying operations (UUID v4). Equivalent to the REST Idempotency-Key header." }, "correlation_id": { "type": "string", "description": "OPTIONAL non-normative money-path correlation join id (specification.md Section 9.7). Opaque, non-PII token; equivalent to the REST USP-Correlation-Id header. Recipients that do not participate ignore this field without failing the request. Not a substitute for booking_id or payment identifiers." }, "authorization": { "$ref": "#/components/schemas/McpAuthorization", "description": "Privileged-operation authentication when not already established by the MCP HTTP/TLS transport. For privileged_scoped methods, prefer a retained booking_scoped_credential when the business accepts that mechanism (see AuthorizationPolicy); when that credential carries cnf, the accompanying proof is MANDATORY and the credential MUST NOT be presented without it. For privileged_platform methods a platform_key_pop caller sends proof alone, with no credential." } }, "additionalProperties": false }, "McpUspMetaPrivilegedPlatformNoIdempotency": { "type": "object", "required": [ "profile" ], "description": "USP protocol metadata for this MCP tool call. Privileged operation: profile is REQUIRED and authentication MUST satisfy Section 10.1.6. Platform-level privileged call without an idempotency key (e.g. waitlist list). Same authentication rules as McpUspMetaPrivilegedPlatform, including platform_key_pop presented as authorization.proof with no credential. Note this wrapper is used by methods that create nothing, so no booking_scoped_credential is issued on them.", "properties": { "profile": { "type": "string", "format": "uri", "description": "Platform profile URI for capability negotiation and identity binding (MCP equivalent of the REST USP-Agent / UCP-Agent header). REQUIRED on privileged operations. The business fetches this URI over HTTPS with no redirects and caches by URI (minimum 60s TTL floor). See specification.md Sections 8.2.2 and 10.1.6." }, "correlation_id": { "type": "string", "description": "OPTIONAL non-normative money-path correlation join id (specification.md Section 9.7). Opaque, non-PII token; equivalent to the REST USP-Correlation-Id header. Recipients that do not participate ignore this field without failing the request. Not a substitute for booking_id or payment identifiers." }, "authorization": { "$ref": "#/components/schemas/McpAuthorization", "description": "Privileged-operation authentication when not already established by the MCP HTTP/TLS transport. For privileged_scoped methods, prefer a retained booking_scoped_credential when the business accepts that mechanism (see AuthorizationPolicy); when that credential carries cnf, the accompanying proof is MANDATORY and the credential MUST NOT be presented without it. For privileged_platform methods a platform_key_pop caller sends proof alone, with no credential." } }, "additionalProperties": false }, "McpUspMetaPrivilegedScoped": { "type": "object", "required": [ "profile" ], "description": "USP protocol metadata for this MCP tool call. Privileged operation: profile is REQUIRED and authentication MUST satisfy Section 10.1.6. Scoped privileged call on an existing booking, hold, waitlist entry, or registry registration: same platform mechanisms as privileged_platform, and SHOULD prefer booking_scoped_credential via authorization when the business accepts it, accompanied by the platform_key_pop proof its cnf binding requires.", "properties": { "profile": { "type": "string", "format": "uri", "description": "Platform profile URI for capability negotiation and identity binding (MCP equivalent of the REST USP-Agent / UCP-Agent header). REQUIRED on privileged operations. The business fetches this URI over HTTPS with no redirects and caches by URI (minimum 60s TTL floor). See specification.md Sections 8.2.2 and 10.1.6." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Idempotency key for state-modifying operations (UUID v4). Equivalent to the REST Idempotency-Key header." }, "if_match": { "type": "string", "description": "OPTIONAL conditional-write precondition, carrying the opaque `revision` the platform last observed for the addressed resource. MCP equivalent of the REST If-Match header. When present, the business MUST apply the write only if the resource's current revision matches, and MUST reject with revision_mismatch otherwise rather than applying it - this is what stops two agents holding the same booking_scoped_credential from silently clobbering each other. Omit it to write unconditionally. Defined for bookings and waitlist entries, which carry `revision`; usp_availability_release shares this wrapper but a hold has no revision and no update operation, so a business MUST ignore if_match there. Interaction with idempotency_key: an idempotent REPLAY returns the stored original response WITHOUT re-evaluating this precondition, since re-checking would fail a retry of an already-successful call. Note this field falls INSIDE the usp_p proof digest, which strips only _meta.usp.authorization, so on MCP the precondition is covered against tampering by an intermediary - REST has no equivalent protection for its If-Match header." }, "correlation_id": { "type": "string", "description": "OPTIONAL non-normative money-path correlation join id (specification.md Section 9.7). Opaque, non-PII token; equivalent to the REST USP-Correlation-Id header. Recipients that do not participate ignore this field without failing the request. Not a substitute for booking_id or payment identifiers." }, "authorization": { "$ref": "#/components/schemas/McpAuthorization", "description": "Privileged-operation authentication when not already established by the MCP HTTP/TLS transport. For privileged_scoped methods, prefer a retained booking_scoped_credential when the business accepts that mechanism (see AuthorizationPolicy); when that credential carries cnf, the accompanying proof is MANDATORY and the credential MUST NOT be presented without it. For privileged_platform methods a platform_key_pop caller sends proof alone, with no credential." } }, "additionalProperties": false }, "McpUspMetaPrivilegedScopedNoIdempotency": { "type": "object", "required": [ "profile" ], "description": "USP protocol metadata for this MCP tool call. Privileged operation: profile is REQUIRED and authentication MUST satisfy Section 10.1.6. Scoped privileged read (e.g. get booking / get waitlist entry) without an idempotency key. Same authentication rules as McpUspMetaPrivilegedScoped.", "properties": { "profile": { "type": "string", "format": "uri", "description": "Platform profile URI for capability negotiation and identity binding (MCP equivalent of the REST USP-Agent / UCP-Agent header). REQUIRED on privileged operations. The business fetches this URI over HTTPS with no redirects and caches by URI (minimum 60s TTL floor). See specification.md Sections 8.2.2 and 10.1.6." }, "correlation_id": { "type": "string", "description": "OPTIONAL non-normative money-path correlation join id (specification.md Section 9.7). Opaque, non-PII token; equivalent to the REST USP-Correlation-Id header. Recipients that do not participate ignore this field without failing the request. Not a substitute for booking_id or payment identifiers." }, "authorization": { "$ref": "#/components/schemas/McpAuthorization", "description": "Privileged-operation authentication when not already established by the MCP HTTP/TLS transport. For privileged_scoped methods, prefer a retained booking_scoped_credential when the business accepts that mechanism (see AuthorizationPolicy); when that credential carries cnf, the accompanying proof is MANDATORY and the credential MUST NOT be presented without it. For privileged_platform methods a platform_key_pop caller sends proof alone, with no credential." } }, "additionalProperties": false }, "AuthorizationPolicy": { "$ref": "https://usp-protocol.dev/schemas/profile.json#/$defs/AuthorizationPolicy" }, "AuthorizationMechanism": { "$ref": "https://usp-protocol.dev/schemas/profile.json#/$defs/AuthorizationMechanism" } }, "errors": { "USPProtocolError": { "code": -32600, "message": "USP protocol error. Business outcome errors are returned in result.structuredContent.messages[], not as JSON-RPC errors. See §9.4.", "data": { "type": "object", "required": [ "code", "content" ], "properties": { "code": { "type": "string", "description": "Machine-readable protocol error code from §9.4.3 Protocol Errors. This is the authoritative discriminator: the JSON-RPC number is a coarse bucket and several codes deliberately share one, so clients MUST branch on this value rather than on the number. Every enum member appears in the §9.4.3 matrix with its REST status and Problem type slug.", "enum": [ "invalid_request", "validation_error", "invalid_profile_url", "profile_unreachable", "profile_malformed", "profile_not_trusted", "booking_not_found", "entry_not_found", "authentication_required", "signature_missing", "signature_invalid", "key_not_found", "digest_mismatch", "algorithm_unsupported", "signature_expired", "pop_proof_required", "pop_proof_missing", "pop_proof_invalid", "pop_key_mismatch", "pop_proof_replayed", "proof_nonce_required", "revision_mismatch", "idempotency_conflict", "cursor_expired", "range_too_wide", "rate_limited", "hold_limit_exceeded", "version_unsupported", "service_unavailable", "server_error" ] }, "content": { "type": "string", "description": "Human-readable error description." }, "mechanism": { "$ref": "https://usp-protocol.dev/schemas/profile.json#/$defs/AuthorizationMechanism", "description": "OPTIONAL discriminator naming the mechanism the failure relates to. RECOMMENDED on signature_missing, signature_invalid and signature_expired, which now cover both RFC 9421 signatures and platform_key_pop proofs and are otherwise ambiguous to a caller deciding what to correct." }, "nonce": { "type": "string", "description": "REQUIRED on proof_nonce_required, absent otherwise. The server-supplied nonce the platform MUST include in a freshly built proof when retrying. A business MAY enable nonces unilaterally without a flag day, because platforms are required to support being challenged even when they never volunteer a nonce." } } } } }, "x-usp-securitySchemes": { "HttpMessageSignature": { "mechanism": "http_message_signature", "description": "RFC 9421 HTTP Message Signatures. On MCP-over-HTTP, present Signature / Signature-Input on the HTTP request; keys resolve from the keys (or legacy signing_keys) array of the platform profile referenced by _meta.usp.profile. Covered components and parameters are identical to the REST binding (UCP's set: @method, @authority, @path, plus @query / agent header / idempotency-key / content-digest / content-type when present; 'created' OPTIONAL; replay protection via the signed idempotency key). RECOMMENDED default. Same mechanism as openapi/usp-rest.json components.securitySchemes.HttpMessageSignature." }, "PlatformKeyPop": { "mechanism": "platform_key_pop", "description": "Platform key proof-of-possession. Permissionless: the caller generates an ephemeral key, never transmits the private half, and proves possession on each privileged request; the business records the RFC 7638 thumbprint (jkt) as the platform identifier. Carry the proof in _meta.usp.authorization.proof on BOTH MCP transports - stdio and HTTP-SSE - rather than on a DPoP HTTP header, so there is one client code path and a business behind an SSE gateway need not know its externally visible URL. The MCP proof deliberately differs from the REST one: typ is usp-pop+jwt rather than dpop+jwt, and it binds usp_m (the JSON-RPC method name) and aud (a published business profile URI) in place of htm and htu, plus usp_p over the canonicalized params. The differing typ means neither proof can be replayed as the other before claim checking. This mechanism is also what makes a booking_scoped_credential sender-constrained via cnf.jkt. Same mechanism identifier as openapi/usp-rest.json components.securitySchemes.PlatformKeyPop, though the two bindings carry it differently. See specification.md Section 9.2.2 and Section 10.1.6." }, "BookingScopedCredential": { "mechanism": "booking_scoped_credential", "description": "Booking- or waitlist-entry-scoped capability credential issued at create. Shape defined at schemas/profile.json#/$defs/BookingScopedCredential. Carry via _meta.usp.authorization (mechanism=booking_scoped_credential, credential=) or, when MCP is over HTTP, via Authorization: Bearer if the business documents that wire form. When the credential carries a cnf confirmation key it is sender-constrained and MUST be accompanied by a platform_key_pop proof over the bound key; see specification.md Section 10.1.6. Same mechanism as openapi BookingScopedCredential." }, "OAuth2Bearer": { "mechanism": "oauth2_bearer", "description": "OAuth 2.0 Bearer. Prefer HTTP Authorization header on MCP-over-HTTP; otherwise _meta.usp.authorization. Same mechanism as openapi OAuth2Bearer." }, "ApiKey": { "mechanism": "api_key", "description": "Pre-shared API key. Prefer HTTP Authorization: Bearer on MCP-over-HTTP; otherwise _meta.usp.authorization. Same mechanism as openapi ApiKey." }, "MutualTLS": { "mechanism": "mtls", "description": "Client-certificate authentication on the MCP-over-HTTP TLS session. Not expressible inside _meta; set _meta.usp.authorization.mechanism=mtls only as an explicit declaration that the TLS client cert is the credential. Same mechanism as openapi MutualTLS." } } } }