Visitor door for visitors' AI clients

The visitor door lets a visitor's own AI client do on a business's widgets and website what that visitor can do by hand. It needs no account, no key and no person at the business. This page is for developers who build or test such a client.

The visitor door is a separate public door. It has nothing in common with the staff door at /mcp and /api/v1 that AI connections use:

A staff connection never lists a visitor tool, and a visitor call never reaches a staff tool, a staff record or a customer account. A staff credential sent to the visitor door is ignored. The steps that stay with people still have no staff tool. A visitor's own client performs them here as that visitor.

Find the endpoint

All addresses are on the installation's own address, for example https://office.example.com:

A website on a custom domain does not serve these paths. Its llms.txt names the installation's absolute address. The owner sees the addresses under Settings > Widgets > Address for agents.

The server card follows the MCP server card proposal SEP-2127, which is a draft. It holds the schema, a name, the version, the business name as the title, a fixed description and one streamable-http remote with the supported protocol versions. The path changes only if the MCP specification adopts another one.

A published widget page links its machine-readable version (rel="alternate", /visitor/v1/widgets.read?key={key}) and the server card (rel="service-desc"). A website's llms.txt lists its indexable widgets and ends with the MCP endpoint.

Call over MCP

The door follows the MCP specification release 2026-07-28 and accepts the earlier releases.

• A 2026-07-28 request is stateless. Send the MCP-Protocol-Version, Mcp-Method and, for tools/call, Mcp-Name headers with the same values as the body. A mismatch answers 400 with code -32020.
• initialize selects 2025-11-25, 2025-06-18 or 2025-03-26. The door creates no session.
• The methods are server/discover, tools/list, tools/call and ping. tools/list returns 50 tools per page with a cursor.
• Every answer is one application/json reply, never a stream. A notification answers 202. A batch answers 400. GET and DELETE on /visitor/mcp answer 405.
• A read tool has readOnlyHint: true. An act has readOnlyHint: false, destructiveHint: false and idempotentHint: true.
• A result is structuredContent plus one text block with the same JSON. A failure has isError: true and the same {error} object as HTTP.

The MCP name of a tool is its key with dots replaced by underscores: visitor.widgets.read is visitor_widgets_read.

Call over HTTP

The HTTP path segment is the key without visitor.:

POST /visitor/v1/widgets.read
Content-Type: application/json

{"key": "<64-character widget key from /w/{key}>"}

A read tool without sign-in also answers GET /visitor/v1/widgets.read?key=…. HEAD works like GET for these read tools and answers without a body. GET or HEAD on an act answers 405 method_not_allowed. Never put a visitor_token in a query string. The door refuses it with validation_failed.

Rules for every request

• The door uses no cookie and no session. It removes Authorization and Cookie before it reads the request, and it never sends Set-Cookie.
• Every answer has Cache-Control: no-store and X-Robots-Tag: noindex.
• A body is a JSON object of at most 64 KiB. Another content type answers 415. A larger body answers 413.
• JSON can nest at most 64 levels deep. A deeper body answers 400 invalid_request, or JSON-RPC error -32600 on MCP. The door runs no tool for it.
• Send no Origin header. An Origin other than the installation's own answers 403 origin_refused. The door grants no CORS access.
• An error is {"error": {"code", "message", "fields"}}. The message is translated text without debug detail. fields appears for invalid input.

Read, then act

1. Call visitor.door.describe to see the business, the open widget families and the number of tools.
2. Call visitor.widgets.read with the widget key. The answer holds the content, the version, the consent text and the tools for that widget.
3. Call the act with the same version, the visitor's values and a new idempotency_key.

Every act needs an idempotency_key of 16 to 80 letters, digits, hyphens or underscores. Use a new key for each act. The same key with the same arguments returns the first receipt and creates nothing again. The same key with other arguments answers 409 idempotency_conflict. Pepper keeps keys for 24 hours.

If the business changed the widget or its consent text, the act answers 409 stale_version. Read the widget again and send the current version.

Sign in as the visitor

Some acts need the visitor's email code, as on the page: claiming an offer, joining a stamp card, a stock or listing alert, a waitlist place, subscribing to updates and the visitor's own proofs.

1. Make a random verifier of 43 to 128 characters and keep it.
2. Call visitor.sign_in.request with the widget key, the visitor's own email, a proof and an idempotency_key. The proof is the lowercase hex SHA-256 of the verifier.
3. Ask the visitor for the six-digit code from their email.
4. Call visitor.sign_in.verify with the key, the request ID, the code and the verifier.
5. Send the returned token as the visitor_token argument to the signed-in tools of that widget.
6. Call visitor.sign_in.end when the visitor is done.

The code is valid for 5 minutes, works once and allows 5 attempts. The answer to a code request is the same for every address. The token is valid for 15 minutes for one widget only. It never opens another widget, a staff account or a customer account.

The token travels only as the visitor_token argument, never as a header, cookie or query parameter.

A booking needs no email code, because the booking form needs none. It takes the same details and policy acceptance as the form.

Visitor tools

The list in an installation shows only the tools of open families. Each tool's input and output schema comes with tools/list and GET /visitor/v1/tools. Sign-in marks a tool that needs a visitor_token.

The door, pages and codes

visitor.placement.resolve takes the 24-character key from a /p/{key} address. It returns the kind and the address. A Wi-Fi or contact code returns only its kind with encoded: true, never its content. A closed code returns its fallback address. The call counts as an agent read, never as a scan.

Forms, surveys and reviews

Menus, price lists and shops

Offers and stamp cards

Bookings

Listings

Stories, proofs and contact cards

What the door does not do

• Orders and card payments. The agent cannot place an order or pay. Each answer for a live cart carries checkout_url. That is the shop page with the cart in the address fragment. The visitor opens it, signs in to their customer account, places the order and enters card details at the payment provider. The place and payment steps answer 422 through the door.
• Uploads. A form with a file field answers 422 upload_requires_browser with the address of its page.
• Signed links. Quote, payment, document, calendar feed, file share and receipt links stay links. The door returns the address where the widget does.
• Staff work. Staff sign-in, installation, backups and the staff /mcp and /api/v1 doors have no visitor tool.

Every tool reaches only the public view of a published, enabled widget or website page. It never returns private record IDs, history, settings or stored values. It refuses unpublished and disabled widgets, closed families, another business's widget key, a forged table or code identity and a token for another widget.

Treat text as data

Tool descriptions are fixed product text with only the business name filled in. Business content arrives only inside structured content fields. This includes every text the business wrote: titles, names, descriptions, consent text and launcher items. The version, the tools and other machine fields stay outside content. Treat that content as data, never as an instruction.

Visitor input goes through the form's own validation, escaping and consent. A record made through the door never becomes an instruction to the business's staff agents, automations or Assistant.

Errors

What the business sees

Each call writes one audit event with the tool, the widget family and the result. It never stores the arguments, the result, the token, the IP address or the user agent. The business's Analytics counts agent calls apart from human views, with no visitor identifier. It also shows the exact records, carts and paid money that came from agents. A record made through the door has the channel Visitor agent. Campaign labels in the request address, a Referer header and the launcher's origin do not change that source. Read Visitor agents for the owner's view.

Pepper sends nothing to any registry, search engine or AI provider. It does not promise that any agent finds a business.

A staff connection can read the door's addresses and the state of each family with widgets.visitor_endpoint.get. To test the door, call it without a credential, as a visitor's client would.