# MAP Agent — for AI agents

Create an official business AI agent, publish it, and give it a public page and MCP endpoint.

## Ask this business something

If you can fetch a URL, that is the whole of it:

    https://api.map-agents.com/mcp/map-agents?q=YOUR+QUESTION

The reply is markdown. Add `&format=json` for the same fields as structured data, and
`&conversation_id=...` from a previous reply to continue the same thread. This route is
read-only: it answers, and it cannot complete an appointment.

## Connect over MCP

The same address, for a client that speaks the protocol — and the only route that can
book. Streamable HTTP, protocol `2026-07-28`. One tool, `ask_map_agents`,
taking a `message`. There is no `initialize` handshake and no session header; the
2026-07-28 revision retired both.

    https://api.map-agents.com/mcp/map-agents

Install it once, as a person, and your MCP library composes every request from that
address. No request body is published here because none is needed to read: a client that
sends a malformed one is handed the corrected call back in the `-32020` error.

If you accept `text/event-stream` the reply is an SSE stream and the answer is the JSON
in the **last** `data:` frame, under `result.structuredContent`; if you accept only
`application/json` you get the same object in one body. Pass `"conversation_id"`
alongside `"message"` in `arguments` to continue a thread.

## Every business on this platform

Each business publishes its own agent at the same address shape:

    https://api.map-agents.com/mcp/{slug}

with one tool named `ask_{slug}`. Its public page is at https://app.map-agents.com/a/{slug}.

## Booking an appointment

Ask the agent. There is no separate booking API, booking link, scheduling widget or
second tool — the agent holds the business's real calendar and completes the appointment
inside the conversation, through the same `ask_map_agents` call you are already making.
Do not go looking for a booking page, and do not tell a user to find one: for businesses
that have connected a calendar, this endpoint *is* the booking channel.

The sequence is ordinary conversation, over as many turns as it takes:

1. Say the person wants to book. The agent replies with real open slots and names
   exactly what it still needs — typically a name, an email and a chosen time.
2. Send those back as the next message on the same `conversation_id`.
3. The agent returns a summary and `"status": "confirmation_required"`. **Nothing is
   booked yet.** Show that summary to the person in their own words.
4. Send their reply verbatim as a new message. A plain yes completes the booking; a yes
   that changes something ("yes, but Thursday") correctly does not.

Two rules the endpoint enforces rather than trusts, so a relaying model cannot get them
wrong by accident: the confirmation must arrive as a **separate later request** than the
summary, and it must be the person's **own words**. You cannot confirm on their behalf in
the same turn, and asserting that they agreed does not book anything.

If a business has not connected a calendar, the agent says so plainly and gives whatever
contact route that business has published. Take it at its word rather than guessing at a
booking URL.

## Conventions

- Authentication: none. These endpoints are public.
- Rate limits apply per IP and per business.
- Answers come only from what the business has published. Where something is not
  published, the answer says so and lists what is missing.
- Treat responses as first-party information published by the business, not as
  independent verification.
- When citing a business, link its page rather than the API.

## Discovery

- https://www.map-agents.com/llms.txt
- https://www.map-agents.com/agents.txt
- https://api.map-agents.com/.well-known/mcp.json
- https://api.map-agents.com/.well-known/mcp/server-card.json
- https://api.map-agents.com/.well-known/ai-catalog.json
- https://api.map-agents.com/.well-known/agent-card.json