Docs / Agent Desk
Agent Desk
Not live yet. This is a draft. The ChatSupportHQ endpoint is in development, and details may change before launch. The key words MUST, SHOULD and MAY follow RFC 2119.
Overview
Agent Desk lets a customer's own AI assistant contact a business's support desk, under rules the business sets. The spec defines five things:
- how an agent discovers a desk from a domain,
- which tools it can call,
- how it identifies itself,
- how the person it acts for authorizes it,
- and how the business controls it.
ChatSupportHQ is the reference implementation. Anyone may implement the spec, competitors included. Out of scope for v0.2: payments from agent to business, agent-to-agent negotiation, voice, and in-browser WebMCP.
Discovery file
A desk MUST publish JSON at https://<domain>/.well-known/agent-desk.json:
- served with
Content-Type: application/json, - and with
Access-Control-Allow-Origin: *.
/.well-known/chatsupporthq.json is a supported alias with the same content. Agents SHOULD try the canonical name first.
The file MUST NOT contain secrets, internal ids or customer data. Agents SHOULD cache it for at most 1 hour and MUST NOT treat it as authorization.
Field reference
| Field | Required | Meaning |
|---|---|---|
spec | Yes | agent-desk/<major.minor>. Agents MUST ignore files with an unknown major version. |
name | Yes | Display name of the desk. |
domain | Yes | The business domain. It MUST equal the host the agent first requested, even when the file was reached through a redirect. |
mcp.url | Yes | Remote MCP endpoint. It MAY be on any https origin, not only the business's own. |
mcp.transport | Yes | streamable-http. v0.2 supports no other transport. |
tools | Yes | The tools this desk offers, from the five below. ask and handoff_to_human are always present. |
auth.agent_signature | Yes | web-bot-auth. Unsigned agents are still served, as unverified. |
auth.signature_required_for | No | Tools that refuse unsigned agents. Default empty. Never handoff_to_human. |
auth.user_authorization | No | one-time-code. Left out when the desk can't verify customers. |
auth.required_for | No | Tools that need a user authorization token. |
posture | No | The business's agent posture: default, unverified and journeys. The server enforces it whether or not it is published. |
limits | No | Public action limits, so an agent can skip a request that will be refused. Server-side limits are authoritative. |
human | No | Whether a person can be reached, and when. |
languages, policy_url, contact, updated | No | Plain information. |
JSON Schema
Validate your file against the JSON Schema (draft 2020-12). It is also at /schemas/agent-desk-0.2.json.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://chatsupporthq.com/schemas/agent-desk-0.2.json",
"title": "Agent Desk discovery file",
"type": "object",
"required": ["spec", "name", "domain", "mcp", "tools", "auth"],
"properties": {
"spec": { "type": "string", "pattern": "^agent-desk/[0-9]+\\.[0-9]+$" },
"name": { "type": "string", "minLength": 1, "maxLength": 200 },
"domain": { "type": "string" },
"mcp": {
"type": "object",
"required": ["url", "transport"],
"properties": {
"url": { "type": "string", "format": "uri", "pattern": "^https://" },
"transport": { "const": "streamable-http" }
}
},
"tools": {
"type": "array",
"uniqueItems": true,
"items": { "enum": ["ask", "open_case", "case_status", "request_refund", "handoff_to_human"] },
"allOf": [
{ "contains": { "const": "ask" } },
{ "contains": { "const": "handoff_to_human" } }
]
},
"auth": {
"type": "object",
"required": ["agent_signature"],
"properties": {
"agent_signature": { "const": "web-bot-auth" },
"signature_required_for": {
"type": "array",
"items": { "enum": ["ask", "open_case", "case_status", "request_refund"] }
},
"user_authorization": { "const": "one-time-code" },
"required_for": {
"type": "array",
"items": { "enum": ["open_case", "case_status", "request_refund"] }
}
},
"dependentRequired": { "required_for": ["user_authorization"] }
},
"posture": {
"type": "object",
"properties": {
"default": { "$ref": "#/$defs/posture" },
"unverified": { "$ref": "#/$defs/posture" },
"journeys": { "type": "object", "additionalProperties": { "$ref": "#/$defs/posture" } }
}
},
"limits": { "type": "object" },
"human": {
"type": "object",
"properties": { "available": { "type": "boolean" }, "hours": { "type": "string" } }
},
"languages": { "type": "array", "items": { "type": "string" } },
"policy_url": { "type": "string", "format": "uri" },
"contact": { "type": "string" },
"updated": { "type": "string", "format": "date-time" }
},
"$defs": { "posture": { "enum": ["block", "tolerate", "serve"] } }
}
This is a short version. The downloadable file adds patterns for domain, journey names, currency codes and refund limits.
Examples
A store that serves refunds up to $50, tolerates cancellations and blocks billing disputes.
{
"spec": "agent-desk/0.2",
"name": "Acme Store Support",
"domain": "acme.example",
"mcp": {
"url": "https://api.chatsupporthq.com/agent-desk/v0/acme/mcp",
"transport": "streamable-http"
},
"tools": ["ask", "open_case", "case_status", "request_refund", "handoff_to_human"],
"auth": {
"agent_signature": "web-bot-auth",
"signature_required_for": [],
"user_authorization": "one-time-code",
"required_for": ["open_case", "case_status", "request_refund"]
},
"posture": {
"default": "serve",
"unverified": "tolerate",
"journeys": { "refund": "serve", "cancellation": "tolerate", "billing_dispute": "block" }
},
"limits": {
"request_refund": { "max_amount": 50, "currency": "USD", "per_user_per_30d": 1 }
},
"human": { "available": true, "hours": "Mon-Fri 09:00-17:00 America/New_York" },
"languages": ["en"],
"policy_url": "https://acme.example/support-policy",
"contact": "agents@acme.example",
"updated": "2026-11-20T00:00:00Z"
}
A desk with no way to look up customers. It leaves out user_authorization, so agents use ask and handoff_to_human only.
{
"spec": "agent-desk/0.2",
"name": "Example Blog Help",
"domain": "blog.example",
"mcp": {
"url": "https://api.chatsupporthq.com/agent-desk/v0/blog/mcp",
"transport": "streamable-http"
},
"tools": ["ask", "handoff_to_human"],
"auth": { "agent_signature": "web-bot-auth" },
"human": { "available": false },
"languages": ["en", "de"]
}
A desk that serves everything to verified agents, and only lets unsigned agents ask and reach a person.
{
"spec": "agent-desk/0.2",
"name": "Example Shop Support",
"domain": "shop.example",
"mcp": {
"url": "https://api.chatsupporthq.com/agent-desk/v0/shop/mcp",
"transport": "streamable-http"
},
"tools": ["ask", "open_case", "case_status", "request_refund", "handoff_to_human"],
"auth": {
"agent_signature": "web-bot-auth",
"signature_required_for": ["open_case", "case_status", "request_refund"],
"user_authorization": "one-time-code",
"required_for": ["open_case", "case_status", "request_refund"]
},
"posture": { "default": "serve", "unverified": "block" },
"limits": {
"request_refund": { "max_amount": 25, "currency": "EUR", "per_user_per_30d": 2 }
}
}
Serving the file
The desk doesn't need to control the business's domain. Pick one:
Save the JSON as .well-known/agent-desk.json in your site's root. Make sure it is served with the right headers.
/.well-known/agent-desk.json
Content-Type: application/json
Access-Control-Allow-Origin: *
Cache-Control: public, max-age=3600
Redirect the well-known path to the copy your desk hosts. Keep domain set to your own host.
location = /.well-known/agent-desk.json {
return 302 https://api.chatsupporthq.com/agent-desk/v0/acme/agent-desk.json;
}
The ChatSupportHQ WordPress plugin publishes the file for you once you connect your workspace. No file to edit.
Check what agents will see:
curl -sIL https://acme.example/.well-known/agent-desk.json
curl -sL https://acme.example/.well-known/agent-desk.json | jq .
Verified and unverified agents
- Verified: the request carries a valid Web Bot Auth signature (HTTP Message Signatures, RFC 9421, Ed25519). The desk records the verified operator on every case.
- Unverified: the request is unsigned, or its
Signature-Agentcan't be resolved. The desk recordsoperator: "unverified".
Unverified agents MAY always use ask, request_authorization, verify_authorization and handoff_to_human. Other tools follow posture.unverified (default tolerate), and are refused when listed in auth.signature_required_for.
A signature that is present but invalid, expired, replayed or made with an unknown key is rejected with HTTP 401. It is never downgraded to unverified.
A valid signature proves who holds the key. It does not prove the agent is trustworthy, or that the user agreed to anything.
Tools
Tool names use only [a-zA-Z0-9_-]. Hosts MAY namespace them, for example agentdesk_ask. Every tool returns JSON with ok. Failures carry error.code and error.message and come back as MCP results with isError: true. Responses that change a case include case_id, status and receipt_url.
| Tool | Input | Output |
|---|---|---|
ask | question (max 2,000 chars), language?, journey? | answer, sources, confidence, suggest_open_case, receipt_url |
open_case | summary, journey, user.email, authorization_token, details?, idempotency_key | case_id, status: "open", receipt_url |
case_status | case_id, authorization_token | status, updates, next_step |
request_refund | case_id, order_ref, amount?, currency?, reason, authorization_token, idempotency_key | decision (approved, needs_human or declined), reason, case_id |
handoff_to_human | case_id?, reason?, preferred_contact?, user? | case_id, status: "with_human", eta?, fallback? |
askMUST say so when the sources don't support an answer, and setsuggest_open_case: true. It is a public model call that costs the business money, so desks SHOULD rate-limit it.request_refundnever moves money. Amounts over the limit returnneeds_human. An approved decision goes to the merchant as a signedrefund.approvedwebhook, and the case isresolvedonly when the merchant confirms.handoff_to_humanis always available, needs no token and MUST NOT be disabled by plan, limit or cap.
An example call and result for ask:
// arguments
{ "question": "Can I return an opened item?", "journey": "refund" }
// result content (JSON)
{
"ok": true,
"answer": "Yes, within 30 days if it is unused. Opened items get store credit.",
"sources": [{ "title": "Returns policy", "url": "https://acme.example/returns" }],
"confidence": "high",
"suggest_open_case": false,
"receipt_url": "https://chatsupporthq.com/r/acme/…"
}
User authorization
Tools listed in auth.required_for need a token for one specific user. Two MCP tools get it:
- The agent calls
request_authorizationwith{ "email", "scope" }. - The desk emails a 6-digit code, but only if that address is a known customer. The response is the same either way, so it never reveals whether an account exists.
- The user reads the code and gives it to their agent.
- The agent calls
verify_authorizationwith{ "email", "code" }and gets anauthorization_token.
| Rule | Value |
|---|---|
| Code life | 10 minutes, single use, stored hashed |
| Code sends | At most 3 per email per hour, plus per-operator, per-IP and per-workspace daily caps |
| Verification attempts | At most 5 per code |
| Token | Opaque, 256-bit, stored hashed, bound to the email, operator and scopes |
| Token life | 1 hour, revocable. Refunds need a token from the last 15 minutes. |
The desk needs a source of truth for "is this a customer". It MUST be a signed customer.lookup webhook, a connected store such as Stripe or Shopify, or addresses already seen on this desk. Without one, the desk leaves user_authorization out of the file.
Posture
The merchant sets a posture for each journey, plus one for unverified agents. When both apply, the stricter one wins.
| Posture | Behavior |
|---|---|
block | Requests for this journey get agents_not_accepted and a pointer to the human channel. |
tolerate | The agent can ask, open_case and case_status. Actions always go to a person. |
serve | The agent can use every tool the desk offers, inside limits. |
Errors
Transport level (HTTP)
| Code | HTTP | Meaning |
|---|---|---|
signature_invalid | 401 | A signature is present but invalid, expired, replayed or unverifiable. Unsigned requests are not an error. |
rate_limited | 429 | Too many requests. Retry-After is set. |
Tool level (MCP result with isError: true)
| Code | Meaning |
|---|---|
authorization_required | The tool needs a user authorization token. |
authorization_invalid | Wrong, expired or out-of-scope token or code. |
signature_required | This tool needs a verified agent. |
agents_not_accepted | Posture is block for this journey. |
limit_exceeded | Over the merchant's limit. Use handoff_to_human. |
rate_limited | A tool-level cap was hit, for example code sends. |
not_found | Unknown case_id. |
Changelog
- 0.2, 20 Nov 2026: verified and unverified agents;
mcp.urlon any origin; static, redirect and WordPress serving; customer lookup and code abuse caps; canonical nameagent-desk.json; plain tool names;handoff_to_humanneeds no case or token; errors split into transport and tool level; refunds approved by signed webhook. - 0.1, 20 Nov 2026: first draft.
MIT License, Copyright (c) 2026 DishIs Technologies LLC. Questions or a desk you'd like to connect? hello@chatsupporthq.com