Search enabled dealer inventory through one MCP

Marketplace access with AAP and A2A

Read marketplace information and participating locations, inspect inventory filters, search listings, retrieve vehicle details, and submit consented inquiries through the Car Handshake marketplace agent. Customers do not need an account or API key.

Car Handshake AAP agent card · Endpoint: https://mcp.carhandshake.com/a2a

The agent searches inventory from participating US dealerships and supported Canadian dealerships outside Quebec that enabled public AI search. Website and AI publication are separate choices, so their listings can differ.

Send an HTTP POST with Content-Type: application/json to the endpoint advertised in the card. The transport is A2A 1.0 over JSON-RPC 2.0; the method is SendMessage. Follow the card for the current AAP version and request and response schemas.

Operations and schemas

• dealer.information: Request schema · Response schema
• inventory.facets: Request schema · Response schema
• inventory.search: Request schema · Response schema
• inventory.vehicle: Request schema · Response schema
• lead.submit: Request schema · Response schema

Example: three used SUVs under US$25,000

curl 'https://mcp.carhandshake.com/a2a' \
  -H 'Content-Type: application/json' \
  --data '{
  "jsonrpc": "2.0",
  "id": "inventory-example-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "inventory-example-1",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "type": "inventory.search.request",
            "filters": {
              "condition": [
                "used"
              ],
              "body": [
                "suv"
              ],
              "price_max": 25000
            },
            "pagination": {
              "skip": 0,
              "limit": 3
            },
            "privacy": {
              "anonymous": true
            }
          }
        }
      ]
    }
  }
}'

The response payload is in result.message.parts[].data. The following is an illustrative response with no matches, not a statement about current inventory. A successful search with matches includes vehicle records and source links. Check for a JSON-RPC error before reading the result.

{
  "type": "inventory.search.response",
  "data": {
    "total": 0,
    "skip": 0,
    "limit": 3,
    "vehicles": []
  }
}

A client must support HTTP POST or an A2A integration to invoke the service. Reading the card alone does not connect an assistant. For lead.submit, collect explicit contact consent and include the selected vehicle_of_interest.vehicle_id plus its identifying fields from inventory results and a stable idempotency_key. The server rechecks the listing’s seller before storing the request. It does not accept an unaddressed marketplace inquiry or treat a VIN alone as a choice of seller.

Aggregate AAP search supports the first 50 matches; use MCP or Poppy cursors for deeper shopping results. Exact VIN or stock searches cannot be combined with a free-text query, and facets do not accept VIN or stock filters. Rooftop-name filters are dealer-specific. For vehicle detail, all supplied identifiers must match the same listing; use country CA for Canadian listings and the exact vehicle_id when an identifier matches multiple dealers.

Auto Agent Protocol specification

Personal Agent Protocol guest API

Car Handshake publishes a Personal Agent Protocol (PAP) discovery document at /.well-known/poppy.json. Its OpenAPI interface provides ten operations for vehicle shopping, search, detail, comparison, dealership discovery, and consented contact with the selected vehicle’s dealer. Car Handshake PAP discovery document

Customers do not sign in. Personal agents authenticate with their published client metadata and signed assertions, obtain a guest session, and send its token with a fresh DPoP proof on each API request. Search uses only AI-enabled inventory. Contact tools require explicit confirmation, consent, and a stable idempotency key; a test-drive or appraisal request is not a confirmed appointment or valuation.

Read the OAuth server metadata and OpenAPI document before calling the API. The resource is the issuer URL. Guest sessions have no account scopes, browser session, or linked customer account. The AAP extension also links to the separately available anonymous MCP, A2A, and website REST interfaces.

Issuer and resource: https://mcp.carhandshake.com/poppy · OAuth server metadata · Poppy OpenAPI document

Personal Agent Protocol is an open draft standard. The document follows version 0.1 and changes with the draft.

Personal Agent Protocol specification

Browser tools with WebMCP

Browsers that expose WebMCP can use the tools registered on Car Handshake pages. Marketplace tools search the website catalog, retrieve a listing or dealership, and send a consented inquiry or test-drive request through the selected dealer’s AAP agent when available. Vehicle and dealer pages use their own dealer’s agent. Navigation and US/Canada market changes update the tool context. Website and AI-search publication are separate dealer choices, so WebMCP website results can differ from MCP, A2A, and Poppy results.

Generic MCP setup

Pinned v1 contract: https://mcp.carhandshake.com/mcp/v1

Generic MCP clients and supported Gemini surfaces can use the canonical Streamable HTTP endpoint above. For ChatGPT, install the published plugin through the setup link. Claude and Perplexity have dedicated endpoints and tool capabilities; use each assistant's setup guide to connect the appropriate version.

Open integration documentation · View machine metadata · View A2A agent card

What it searches

Only inventory from participating US dealerships and supported Canadian dealerships outside Quebec that have enabled public AI search. Website publication is a separate dealer choice.

Portable output

Vehicle shopping returns at most six ranked listings while retaining the complete aggregate total, relation, fallback details, and next cursor. Results also include exact distance, listing freshness, dealer location, match reasons, and direct source links.

Contact remains consented

Inquiry, test-drive, and trade-in tools require explicit consent and idempotency. A requested appointment is not confirmed until the dealership responds.

Gemini availability is surface-specific

Consumer setup uses a custom Connected App in Gemini Spark; it is not a public consumer directory listing. Google Cloud Marketplace and Gemini Enterprise publication remain a separate architecture-review process.