web/docs/connect-an-agent.md

Connect an agent to AimoPilot

AimoPilot speaks two open interfaces with the same operations and the same refusals:

• MCP (Model Context Protocol) over Streamable HTTP at /api/mcp, and at a per-kitchen connector address /api/mcp/c/<token> for assistants that can only be given a URL (section 0). Protocol revision 2026-07-28, plus the 2025-era handshake (2025-11-25 and earlier) that most clients still send.
• REST described by OpenAPI 3.1 at /api/v1/openapi.json.

An agent that knows only the base URL can find both: /.well-known/api-catalog (RFC 9727), /.well-known/dock.json (AimoPilot's own manifest) and /llms.txt.

The kitchen's own agent in the store is one more client of the same tool table and the same gate: what it can look up, an outside agent can look up, as structured data. What we assumed, what is mocked and what a production deployment would need are in assumptions.md.

What the kitchen's own agent can do, and an outside agent

The store's agent and an outside agent call the same core functions through the same gate. Nothing below is a side door: every row passes the same mandate check, admission (suspension, licence) and gate.

* carries the buyer's own answer: asked through the client's form when it can show one; otherwise relayed and recorded as not verified.

Which kitchens an outside agent can buy for. Every kitchen has a mandate and a connector address: the two built-in demo kitchens (kaari, laakso), a visitor's hotel kitchen made by scanning the wall's QR code (its approver is the visitor's phone), and an account kitchen anyone can open at /k/signup (its terms are signed by the account itself). Account and visitor kitchens' keys are held by the server in this demo; in production the kitchen holds its own key (see assumptions.md).

What can change under an agent.

• A kitchen that tightens its rules reissues its mandate; every earlier mandate is refused from that second (rule mandate_window).
• When the wholesaler enforces crash-test licences (DOCK_LICENCE_ENFORCE=on), the gate applies the stricter of the mandate and the licence the agent earned on the public crash test; an agent with no licence bound to it sends every order to a person. The result says when the licence, not the mandate, did.
• A relayed answer ("the chef said yes") is recorded as relayed, not verified. It does not count as a person's: where it matters, the order goes to a named person's sign-off.

The examples use a local server. Replace http://localhost:3000 with the deployed URL.

0. Connect a consumer assistant with only a URL

Consumer assistants (the Claude apps, ChatGPT) let a person add a remote MCP server by URL, with OAuth or with no sign-in, but not with the two request headers below. So every kitchen also has a connector address:

https://<dock>/api/mcp/c/dk_<43 random characters>

The token in the path stands for that kitchen's signed mandate and agent id, which stay on the server. A call through the address is exactly a call to /api/mcp with those headers: the same mandate check, the same gate, the same live-lookup allowance, the same human sign-off. It adds nothing. No tool approves an order, and the token is not an approval proof.

Limits on one address

A leaked address cannot spend beyond the mandate:

• Above the per-order limit, a named person signs off on their phone.
• The weekly budget is a hard cap that no sign-off lifts.
• Out-of-mandate products are refused.

To bound load, each address also has its own limits. They come on top of the per-agent live-lookup allowance, which is shared with every other door of the same agent:

Connector refusals are written to the ledger at most once per address and reason every ten minutes, so a hammered address cannot flood it.

What the consumer assistants accept (vendors' own docs, read 2026-11-13)

Most vendor pages carry no date. Where one did, it is given.

So a plain URL is enough for the leading assistants: Claude on every plan, ChatGPT on Business/Enterprise, Claude Code, and Gemini CLI. AimoPilot does not implement OAuth. The one consumer assistant that seems to need it, the Gemini app, is not offered in Finland anyway.

Sources:

• Claude:
  • add an unlisted connector
  • authentication
  • lazy authentication
  • building
  • getting started
  • troubleshooting
  • help centre: custom connectors (updated late October 2026)
  • help centre: connectors on mobile (updated the week of 9 November 2026)
• ChatGPT:
  • help centre: custom MCP servers (updated about 27 October 2026)
  • developer mode
  • Apps SDK auth
• Gemini:
  • Gemini app custom apps
  • Gemini CLI MCP (updated 6 October 2026)
  • move to Antigravity CLI (19 May 2026)
• Other:
  • Claude Code MCP
  • MCP authorization (revision 2026-07-28: authorization is optional; a server that uses it must publish RFC 9728 metadata; CIMD preferred, DCR deprecated)

Menus move. Check the vendor page if a label differs.

Setup in two minutes, once the app is at its public HTTPS address

Copy the kitchen's connector address from the portal ("connect your own agent"), or:

curl -s https://jolly-wondrous-bunny.eur-1.aiven.app/ui-api/connect/kaari | jq -r .connector.url

Claude (claude.ai or Claude Desktop, any plan)

1. Sign in at claude.ai, or open Claude Desktop.
2. Open Customize > Connectors, click Add, then Add custom connector.
3. Fill in:
   • Name: AimoPilot (Ravintola Kaari)
   • Remote MCP server URL: paste the address.
4. Click Continue. If Claude asks how to sign in, choose No sign-in. Then click Add, then Connect.
5. Optional, to avoid a prompt on every step: go to Customize > Connectors > AimoPilot > Tool permissions and set the read tools to Always allow. Leave place_order on Needs approval if you want Claude to ask before ordering.
6. Start a new chat. Check that AimoPilot is switched on under + > Connectors.
7. Type: "Using AimoPilot, order 1,000 litres of lactose-free milk for our kitchen, delivered by Monday." Click Allow once (or Always allow) when Claude asks to use a AimoPilot tool.
8. Answer the question Claude relays from AimoPilot ("1,000 L where you usually order about 100 L?").
9. Pick an option. The approver's phone (or the portal's sign-off QR code) then asks for the sign-off.

The connector also shows up in the Claude mobile app at its next sign-in.

ChatGPT (web; Business or Enterprise/Edu workspace, as an admin or owner on Business)

1. Sign in at chatgpt.com in a browser.
2. Open Plugins, click +, then Add custom MCP server.
3. Fill in:
   • Name: AimoPilot (Ravintola Kaari)
   • Server URL: paste the address.
   • Authentication: No authentication.
4. Tick I understand and want to continue, click Create as a plugin, then install it.
5. In a new chat, type @ and pick AimoPilot, then the same request as above.
6. ChatGPT asks you to confirm each write step (submit_need, respond_to_concerns, choose_option, place_order). Confirm each one. Answer AimoPilot's question when ChatGPT relays it.

On a Pro account, ChatGPT connects only read/fetch tools, so it cannot order.

Claude Code / Gemini CLI

claude mcp add --transport http dock <address>
gemini mcp add --transport http dock <address>   # needs a paid Gemini API key or Code Assist Standard/Enterprise

What was proven, and with which client (local server, 13 November 2026)

To check again against any address: pnpm tsx scripts/connector-smoke.ts <address>. It places one order, which then waits for sign-off.

On a production build (pnpm build && pnpm start), the smoke script reaches pending_approval too. Revoking a demo kitchen's address without the operator secret gets 403.

Before the demo:

• Set DOCK_CONNECTOR_SECRET on the deployment. Otherwise the demo kitchens' addresses change with every restart, and the assistant has to be set up again.
• Make sure the deployment runs this build. The public address was still serving an older build without /api/mcp/c/… on 13 November.

In a chat assistant: questions and sign-off

Most chat assistants cannot show AimoPilot's own form (elicitation), so the assistant relays. These rules are written for a model that has never seen AimoPilot, and they appear in three places: the server instructions, each tool's description, and each result's nextStep.

• waitingFor: "buyer": ask the person AimoPilot's question in plain words with its choices, stop, and pass on their reply. The original request does not count as the answer.
• pending_approval: tell the person in one sentence who must sign off, on their own phone, and stop. Do not retry, place it again, split it, or find a way around it.
• A refusal is final unless nextStep says how to fix it: tell the person, and do not loop.
• After choose_option, place_order needs only requestId. AimoPilot places the quote it signed for that request, so the model never has to copy a long signed token.
• by (the buyer's name) is optional through a connector. When the assistant does not say, AimoPilot records the kitchen's person "through the kitchen's connector". A chat assistant should not have to ask your name.
• If the client declares elicitation but closes the form unanswered (cancel, as Claude Code does headless), the result is form_not_answered. For that request only, the agent may then ask in the chat and send the reply with relay: true. An explicit decline still stops.

The production version: how a buyer organisation would delegate to its assistant

A URL that carries a secret works for a demo, and AimoPilot keeps it narrow:

• one address per kitchen
• revocable and expiring
• rate-limited
• no more than the mandate

It is still a bearer secret, in a place where URLs get copied and logged. Anthropic's connector guide says not to accept tokens in URLs.

The production version is standard MCP authorization (OAuth 2.1), with the mandate kept as the grant:

1. The connection. The buyer's purchasing manager adds https://<dock>/api/mcp (no token) in their assistant.
   • AimoPilot answers 401 with RFC 9728 protected-resource metadata pointing at AimoPilot's authorization server, or at the buyer's own identity provider.
   • The assistant identifies itself with its Client ID Metadata Document (Claude's or ChatGPT's published identity, so no registration step), with PKCE and an RFC 8707 resource.
2. The consent screen is the mandate. The manager signs in with their organisation account and sees what they are delegating:
   • which kitchen, and which categories
   • the per-order limit and the weekly budget
   • who signs off above the limit, and for how long

   On approval, the organisation signs a mandate naming that assistant as the agent: its client id, not a made-up agent id. The access token references the mandate (scope mandate:<id>), is short-lived, and is bound to the client (DPoP), so a copied token is useless. Refresh tokens are revocable from the organisation's portal.

3. Enterprise version. The organisation's IdP issues the assertion, using MCP's enterprise-managed authorization (an identity-assertion grant), so IT decides centrally which assistants may buy and for whom.
4. Nothing else changes.
   • The gate still checks every order in plain code against the signed mandate.
   • Sign-off still happens on the approver's own device with a passkey.
   • The ledger names the assistant's client id and the human who consented.
   • Rate limits are per client and per organisation, in shared storage (the in-memory limits here are per process).

1. Get a mandate

Every call carries the mandate the buyer organisation signed for its agent, plus the agent id it names:

Authorization: Bearer <mandate JWS>      (Authorization: Mandate <jws> works too)
Dock-Agent-Id: <agent id>

The mandate is a JWT (typ: mandate+jwt, aud: dock) signed by the organisation's own Ed25519 key. AimoPilot holds only the organisation's public key. There is no OAuth flow and no AimoPilot account. Listing MCP tools works without a mandate; every tool call checks it.

For local runs, mint one for the fictional demo buyer, Laakso Catering Oy (valid 7 days):

cd web
export DOCK_MANDATE=$(pnpm -s dev:mandate) DOCK_AGENT_ID=agent_laakso_buyer_01

2. Claude Code

claude mcp add --transport http dock http://localhost:3000/api/mcp \
  --header "Authorization: Bearer $DOCK_MANDATE" \
  --header "Dock-Agent-Id: $DOCK_AGENT_ID"

Or check a project-scoped .mcp.json into a repo. Claude Code expands environment variables in it:

{
  "mcpServers": {
    "dock": {
      "type": "http",
      "url": "http://localhost:3000/api/mcp",
      "headers": { "Authorization": "Bearer ${DOCK_MANDATE}", "Dock-Agent-Id": "${DOCK_AGENT_ID}" }
    }
  }
}

Then ask, for example: "Using the dock tools, order 1,000 litres of lactose-free milk for Monday." The tool descriptions steer the model to start with submit_need and to bring AimoPilot's questions back to you rather than answer them itself.

3. Claude Desktop

The simplest way is the kitchen's connector address as a custom connector (section 0): no sign-in, no headers. To present your own mandate instead, go through the mcp-remote bridge, which forwards custom headers (Claude's own custom-header support is a limited beta). Put the headers in a file so the mandate stays out of the process list:

# ~/.dock-headers.txt
Authorization: Bearer <paste the mandate>
Dock-Agent-Id: agent_laakso_buyer_01

claude_desktop_config.json (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "dock": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/api/mcp", "--header-file", "/Users/you/.dock-headers.txt"]
    }
  }
}

Add --allow-http only if AimoPilot runs over plain HTTP on another machine in a trusted network. Loopback and HTTPS need nothing extra.

4. Any other MCP client

Point it at the URL and set the two headers. With the stock TypeScript client:

import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";

const client = new Client({ name: "my-buyer", version: "1.0.0" }, { versionNegotiation: { mode: "auto" } });
await client.connect(
  new StreamableHTTPClientTransport(new URL("http://localhost:3000/api/mcp"), {
    requestInit: { headers: { Authorization: `Bearer ${mandate}`, "Dock-Agent-Id": agentId } },
  }),
);
const { tools } = await client.listTools();
const r = await client.callTool({ name: "read_mandate", arguments: {} });
console.log(r.structuredContent);

pnpm build && pnpm demo:mcp (or pnpm demo:mcp --url http://localhost:3000) does Valio Aimo's example this way, with no LLM and no AimoPilot client code, as a hotel chain's agent. The hotel's purchasing manager joins with a passkey, and the agent gets the hotel's connector address. It looks up products, prices and availability (find_products) and submits the need. It gets good, better and best options, chooses one and places the order. The order is over the agent's €500, so it waits. The manager signs with the passkey, get_order with waitSeconds returns the outcome, and the script verifies the signed receipt. Then four exceptions follow: a stock-out with ranked substitutes, a nut drink refused as a substitute, delivery today past the cut-off, and an order placed alone, then taken back.

Tools

Start every order with submit_need. The lower-level tools below the line stay for follow-up.

There is no tool to approve or decline an order: only the approver can, on their own phone with their passkey.

The intake, step by step

Every intake result is { ok, step, waitingFor, nextStep }. step.state is where the order stands, waitingFor is buyer, agent or nobody, and nextStep names the exact call to make next.

{ "ok": true, "waitingFor": "buyer",
  "step": { "requestId": "req_…", "state": "needs_confirmation",
            "concerns": [{ "key": "quantity_tenfold:1000:L", "message": "1,000 L where you usually order about 100 L: did you mean 100 L?",
                           "confirmable": true, "corrections": [{ "id": "use_100_L", "label": "Make it 100 L" }] }] },
  "nextStep": "AimoPilot found a likely mistake. Ask the buyer: … Then call respond_to_concerns … This answer must come from the human buyer …" }

* The buyer answers, not the agent

respond_to_concerns and answer_questions carry the human buyer's own answer. The agent relays AimoPilot's question and passes on what the buyer says; it must never confirm a likely mistake or answer a question for them. While a confirmation is pending, request_quote and place_order on that request are refused with rule human_input, so the check cannot be skipped by going around the intake.

The MCP specification has no tool annotation for "needs a person" (annotations are only the readOnlyHint, destructiveHint, idempotentHint and openWorldHint hints). What the 2026-07-28 revision does define is elicitation through input_required results: a tool answers with an elicitation/create form, the client shows it to the user (not the model), and retries the call with the user's answer. AimoPilot uses exactly that:

• Client declares the elicitation capability (form mode): AimoPilot asks through the client's form. The agent's arguments, if any, only pre-fill it; what comes back is what counts, and a declined form changes nothing (code buyer_declined). The form is shown and returned by the agent's client, and AimoPilot cannot tell a client that asked its user from one that filled the form in itself, so the answer is recorded as relayed by the client (channel protocol_elicitation, not verified). It settles preferences inside the mandate; where it confirms a likely mistake that matters, the order still goes to a named person's sign-off.
• Client without elicitation (or a 2025-era connection, which this stateless server cannot push requests to): the agent passes the buyer's answer as by and responses / answers, recorded as relayed and not verified. A call with no answer is refused with code human_answer_required. The step also carries answerUrl, a one-time page on AimoPilot (30 minutes, single use, bound to that exact step) where the buyer taps one of AimoPilot's fixed choices themselves; the agent is told to hand it over instead of relaying. Answers there are recorded with the channel answer_link. Whoever holds the link can answer, so without the kitchen's signed-in session on that phone a confirmation that matters (an unusual amount, a rule broken) still goes to a named person's sign-off.

Both tools also carry _meta: { "dock/humanInput": { "required": true, … } } in tools/list and humanInput: true in the manifest; in the OpenAPI document the same two operations carry x-dock-human-input. Those keys are AimoPilot's own, not a standard. Operations for the approver's phone are tagged approver (x-dock-audience: approver); /api/v1/openapi.json?audience=agent leaves them out, so an OpenAPI-to-tools converter never offers an agent a tool to approve orders.

Output schemas in tools/list are published shallow (the top-level fields with their descriptions, one level of shape below): some runtimes send every output schema to their model on each call. The full shapes are in the OpenAPI document.

Results and refusals

Every result has structuredContent (checked against the tool's published output schema) and the same JSON as text for clients that read only text:

{ "ok": true, "order": { "status": "pending_approval", ... },
  "nextStep": "This order now waits for a human sign-off by Aino Virtanen (kitchen_manager) ... Do not retry ..." }

A refusal is a tool result with isError: true. It carries the same code and rule the REST API returns:

{ "ok": false,
  "error": { "code": "policy_rejected", "rule": "weekly_budget", "message": "This €1,322.00 order would take weekly spend to €2,644.00, over the €2,000.00 budget ..." },
  "nextStep": "The weekly budget is a hard limit that no sign-off can lift. Do not retry or split the order; tell the buyer." }

Live price and availability is for short lists only: at most 10 products per call, and per agent at most 30 different products and 30 live lookups an hour. Quotes count, because a quote asks for live prices. Going over is refused with rule live_lookup_limit.

5. Plain REST with curl

Same headers, same flow. The OpenAPI document lists every status and schema.

DOCK=http://localhost:3000
H=(-H "Authorization: Bearer $DOCK_MANDATE" -H "Dock-Agent-Id: $DOCK_AGENT_ID" -H "content-type: application/json")

# start from a structured need; every reply is { step, waitingFor, nextStep } (plus answerUrl when the buyer must
# answer), and step.next is the next call with an example body whose answers are placeholders, never a pre-filled choice
STEP=$(curl -s -X POST $DOCK/api/v1/intake "${H[@]}" \
  -d '{"need":{"item":{"text":"lactose-free milk","category":"milk"},"quantity":{"amount":20,"unit":"L"},"deliverOn":"2026-11-17"},"by":"Aino"}')
echo "$STEP" | jq '{state: .step.state, waitingFor, nextStep, answerUrl, next: .step.next}'
# then POST .step.next.path with the buyer's answer: /intake/{id}/concerns, /answers, /choice, and finally
# POST /orders with just {"requestId": …}: AimoPilot places the quote it signed at the choice.
# "deliverOn" asks for that exact day; "deliverBy" for that day at the latest.

The lower-level calls, for follow-up or a quote built line by line:

# open a request
REQ=$(curl -s -X POST $DOCK/api/v1/requests "${H[@]}" \
  -d '{"text":"20 L lactose-free milk","neededBy":"2026-11-16"}' | jq -r .request.requestId)

# search master data (no live call)
curl -s "$DOCK/api/v1/products?requestId=$REQ&q=milk&attribute=lactose_free&limit=3" "${H[@]}" | jq '[.products[].id]'

# live price and stock for a short list
curl -s -X POST $DOCK/api/v1/availability "${H[@]}" -d "{\"requestId\":\"$REQ\",\"productIds\":[\"VA-1001\"]}" | jq .offers

# signed quote
Q=$(curl -s -X POST $DOCK/api/v1/quotes "${H[@]}" \
  -d "{\"requestId\":\"$REQ\",\"lines\":[{\"productId\":\"VA-1001\",\"quantity\":20}]}")
echo "$Q" | jq '{total: .quote.totalCents, preview: .policyPreview.outcome}'

# order exactly the quote: 201 committed, 202 waits for sign-off (do not retry), 422 refused
curl -s -X POST $DOCK/api/v1/orders "${H[@]}" \
  -d "$(echo "$Q" | jq -c --arg r "$REQ" '{requestId: $r, quoteToken: .quoteToken, lines: [.quote.lines[] | {productId, quantity, unitPriceCents}]}')" \
  | tee order.json | jq '{status: .order.status, error: .error}'

Products, prices and availability in one call, and alternatives (the same as find_products and find_alternatives):

curl -s -X POST $DOCK/api/v1/lookup "${H[@]}" \
  -d '{"text":"lactose-free milk","requiredClaims":["lactose_free"],"quantity":{"amount":1000,"unit":"L"},"deliverOn":"2026-11-16","limit":4}' \
  | jq '{requestId, products: [.products[] | {name, match, price: .live.unitPriceCents, stock: .live.availablePacks, day: .live.meetsDay, orderBy: .live.orderBy}]}'
curl -s -X POST $DOCK/api/v1/alternatives "${H[@]}" -d '{"productId":"VA-1010","quantity":{"amount":1000,"unit":"L"}}' | jq '.alternatives[] | {rank, name, tradeOffs, gate: .gate.outcome}'

After the order:

curl -s "$DOCK/api/v1/orders?status=pending_approval" "${H[@]}"            # what waits for sign-off
curl -s "$DOCK/api/v1/orders/$ORDER?wait=25" "${H[@]}"                     # answers once the person decides
curl -s -X POST $DOCK/api/v1/orders/$ORDER/withdraw "${H[@]}" -d '{"reason":"breakfast cancelled"}'
# change an order: quote the new lines, then POST /orders { requestId, replaces: "<old orderId>" }

POST /orders with only { requestId } also works after POST /quotes: AimoPilot places the latest quote it signed for that request.

Errors are always { "error": { "code", "rule", "message", "details" } }.

6. Verify a receipt without trusting AimoPilot

A committed order's confirmation is a compact JWS (typ: order+jws) signed by the wholesaler. The public keys are an RFC 7517 JWK Set at /.well-known/jwks.json (also /api/v1/keys), Ed25519 per RFC 8037. Any JOSE library can verify it offline:

pnpm verify:receipt order.json --url $DOCK              # fetch the keys
curl -s $DOCK/.well-known/jwks.json > jwks.json
pnpm verify:receipt order.json --jwks jwks.json         # fully offline

The script (scripts/verify-receipt.ts) uses only jose and the published keys. Edit one byte of the receipt and it fails. Without DOCK_WHOLESALER_JWK set, the server makes a new key each time it starts, so keep the JWK Set that was live when the order was signed.

7. Offers from the wholesaler's selling agent

The wholesaler's own agent may offer a kitchen a product worth trying: new in the assortment, in season in Finland, or a like-for-like cheaper per litre, more reliable or lower in carbon than what the kitchen buys every week. Each offer is a signed W3C Verifiable Credential (compact JWS, typ: vc+jwt, type DockProductOffer, Ed25519, addressed with aud to the buyer organisation), checked like a receipt against the published keys:

curl -s $DOCK/api/v1/offers "${H[@]}" > offers.json
pnpm verify:offer offers.json --url $DOCK --org <your org id>

An offer buys nothing: accept_offer (or POST /api/v1/offers/{offerId}/accept) starts an ordinary order, and the same intake, gate and sign-off decide it. Tell the buyer about at most one or two, in plain words, and only on their own answer accept, decline or mute. The format, the reasons and every guardrail are in offers.md.