---
title: JOY Automart Agent Integration Guide
description: Public configuration, usage, authentication, and safety guidance for automated clients interacting with JOY Automart.
last_updated: 2026-09-22
canonical: https://www.joyautomart.com/AGENTS.md
---

# JOY Automart Agent Integration Guide

> This guide defines the public, read-only discovery boundary for automated clients. It does not grant access to Owner/Admin controls, private agents, customer data, internal tools, or write operations.

## Installation

No client package is required to read JOY Automart's public resources. Use an HTTPS client that follows standard HTTP status codes and content types.

```bash
curl --fail --silent --show-error https://www.joyautomart.com/llms.txt
curl --fail --silent --show-error https://www.joyautomart.com/openapi.json
curl --fail --silent --show-error -H 'Accept: text/markdown' https://www.joyautomart.com/
```

### Connect an AI assistant over MCP

JOY Automart runs a public, read-only [Model Context Protocol](https://modelcontextprotocol.io) server at `https://www.joyautomart.com/mcp` (Streamable HTTP, no authentication). Add it as a remote connector in Claude, ChatGPT, Gemini, Copilot or any MCP client:

```json
{
  "mcpServers": {
    "joy-automart": { "type": "http", "url": "https://www.joyautomart.com/mcp" }
  }
}
```

Tools: `search_parts` (English, Bangla or Banglish queries; BDT prices), `get_part`, `search_vehicles`, `get_vehicle` (full public listing detail + QC inspection summary), `get_auction_status` (read-only; live auctions are closed until JOY opens them), `compare_vehicles` (2-4 cars side by side), `get_buying_guide` (bKash/Nagad/Rocket, card and cash-on-delivery terms, Dhaka and nationwide delivery) and `prepare_buyer_handoff`. Every tool is read-only: none orders, reserves or charges. The server card is at [`/.well-known/mcp/server-card.json`](https://www.joyautomart.com/.well-known/mcp/server-card.json). Limit: 60 requests per minute per client.

### Acting for a buyer: agent keys

A JOY customer or trade account can give their AI agent a key at [`/account/ai-agents`](https://www.joyautomart.com/account/ai-agents). The buyer chooses what the key may do (send parts requests, place orders, track orders), a per-order and a per-day limit in BDT, and an expiry of 1 to 90 days. The key is shown once; JOY stores only a fingerprint. Send it to the MCP endpoint as `Authorization: Bearer joyagt_...` and these tools appear:

- `quote_order`: JOY's authoritative BDT total for a basket, priced for the buyer's account. No side effect.
- `place_order`: cash on delivery or approved trade credit only. `accepted_total_bdt` must equal the fresh quote, so a price change is always re-confirmed with the buyer. Orders above either limit are refused.
- `create_rfq`: a parts request to JOY's sourcing team, for parts not in stock or not in the catalogue.
- `get_order_status`, `list_my_orders`: the buyer's own orders only.

Owner and admin accounts cannot issue keys. The buyer or JOY can revoke a key at any time, and JOY can pause all agent orders without affecting human shoppers.

### Product feed

Every currently sellable retail SKU is exported as JSON at [`/api/agent/v1/feed`](https://www.joyautomart.com/api/agent/v1/feed) (paginated, 60 per page): BDT price, stock, minimum order, bulk pricing, fitment candidates, images, warranty and product URL.

The repository also carries a separate stdio MCP adapter for local development; it is not the public endpoint.

## Configuration

Use `https://www.joyautomart.com` as the public website origin. Public discovery resources include:

- `/llms.txt`
- `/llms-full.txt`
- `/index.md`
- `/sitemap.md`
- `/glossary.md`
- `/openapi.json`
- `/sitemap.xml`

Send `Accept: text/markdown` when a Markdown representation of a public SPA page is preferred. Clients should honor `Content-Type`, `Link`, `Cache-Control`, `Vary`, authentication requirements, and HTTP status codes.

## Usage

A safe public discovery flow is:

1. Read `/llms.txt` for the supported public resource index.
2. Read `/index.md` or request the homepage with `Accept: text/markdown` for structured context.
3. Read `/sitemap.md` to locate public product areas.
4. Read `/openapi.json` before making any documented public API call.
5. Treat a `404` from an unadvertised protocol-discovery URL as “not supported.” JOY advertises exactly four agent-protocol documents and serves each of them: [`/.well-known/mcp/server-card.json`](https://www.joyautomart.com/.well-known/mcp/server-card.json) (public read-only MCP at `/mcp`), [`/.well-known/agent-card.json`](https://www.joyautomart.com/.well-known/agent-card.json) (A2A 1.0, authenticated and read-only), [`/.well-known/api-catalog`](https://www.joyautomart.com/.well-known/api-catalog) (RFC 9727) and [`/.well-known/agent-permissions.json`](https://www.joyautomart.com/.well-known/agent-permissions.json). Every other protocol-discovery path returns `404`. Do not infer UCP, ACP, x402, NLWeb, Web Bot Auth or another protocol simply because JOY uses agents internally.

Example public API calls:

```bash
curl --fail --silent --show-error https://www.joyautomart.com/api/health
curl --fail --silent --show-error 'https://www.joyautomart.com/api/parts/marketplace-search?portal=retail&q=brake%20pad&page_size=5'
curl --fail --silent --show-error https://www.joyautomart.com/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_parts","arguments":{"query":"টয়োটা এক্সিও ব্রেক প্যাড"}}}'
```

## Authentication and authorization

Public documentation does not grant mutation authority. Owner/Admin pages, deployments, private HERMES functions, account records, customer or staff information, finance, integrations, production controls, and other privileged operations require the relevant authenticated JOY session and governance decision.

Do not attempt to bypass authentication, CSRF protection, capability restrictions, kill switches, certification gates, rate limits, or audit controls. A public URL that is not documented in `/openapi.json` should not be assumed to be a public API contract.

## Safety

- Do not represent a proposed action as executed unless JOY returns execution evidence for that action.
- Do not invent vehicle compatibility, OEM part numbers, prices, stock, repair procedures, or production status.
- Treat VIN, chassis, engine, model year, drivetrain, market specification, and supersession as relevant fitment inputs where applicable.
- Treat DTC codes and symptoms as diagnostic evidence, not a complete diagnosis.
- Use the minimum required capability and preserve server-side authorization boundaries.
- Respect privacy, rate limits, robots directives, and authenticated/private route exclusions.

## Markdown mirrors

Every public page has a Markdown mirror at the same path with a `.md` suffix (the homepage mirror is `/index.md`). Three ways to reach one:

- Append `.md` to the page path.
- Follow the `Link: <...>; rel="alternate"; type="text/markdown"` response header.
- Send `Accept: text/markdown`; the origin returns the mirror for any route that has one, and the HTML for any route that does not.

Mirrors are served as `text/markdown; charset=utf-8` and carry a `Link: <...>; rel="canonical"` header pointing back at the HTML page, so the two representations are never treated as duplicate content.

## Error handling

Use HTTP semantics directly: `2xx` indicates the requested representation or operation succeeded; `4xx` indicates the client request is unsupported, unauthorized, invalid, or not found; `5xx` indicates temporary server-side unavailability. Do not reinterpret a SPA HTML document as a machine protocol response.

## Sitemap

See the [public sitemap](https://www.joyautomart.com/sitemap.md) and [automotive glossary](https://www.joyautomart.com/glossary.md) for additional navigation and terminology.