Docs / Agent Desk

Agent Desk

Spec v0.2 Draft, 20 Nov 2026 MIT License

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:

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:

/.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

FieldRequiredMeaning
specYesagent-desk/<major.minor>. Agents MUST ignore files with an unknown major version.
nameYesDisplay name of the desk.
domainYesThe business domain. It MUST equal the host the agent first requested, even when the file was reached through a redirect.
mcp.urlYesRemote MCP endpoint. It MAY be on any https origin, not only the business's own.
mcp.transportYesstreamable-http. v0.2 supports no other transport.
toolsYesThe tools this desk offers, from the five below. ask and handoff_to_human are always present.
auth.agent_signatureYesweb-bot-auth. Unsigned agents are still served, as unverified.
auth.signature_required_forNoTools that refuse unsigned agents. Default empty. Never handoff_to_human.
auth.user_authorizationNoone-time-code. Left out when the desk can't verify customers.
auth.required_forNoTools that need a user authorization token.
postureNoThe business's agent posture: default, unverified and journeys. The server enforces it whether or not it is published.
limitsNoPublic action limits, so an agent can skip a request that will be refused. Server-side limits are authoritative.
humanNoWhether a person can be reached, and when.
languages, policy_url, contact, updatedNoPlain information.

JSON Schema

Validate your file against the JSON Schema (draft 2020-12). It is also at /schemas/agent-desk-0.2.json.

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.

acme.example/.well-known/agent-desk.json
{
  "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"
}

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.

_headers (Cloudflare Pages or Workers static assets)
/.well-known/agent-desk.json
  Content-Type: application/json
  Access-Control-Allow-Origin: *
  Cache-Control: public, max-age=3600

Check what agents will see:

shell
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

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.

ToolInputOutput
askquestion (max 2,000 chars), language?, journey?answer, sources, confidence, suggest_open_case, receipt_url
open_casesummary, journey, user.email, authorization_token, details?, idempotency_keycase_id, status: "open", receipt_url
case_statuscase_id, authorization_tokenstatus, updates, next_step
request_refundcase_id, order_ref, amount?, currency?, reason, authorization_token, idempotency_keydecision (approved, needs_human or declined), reason, case_id
handoff_to_humancase_id?, reason?, preferred_contact?, user?case_id, status: "with_human", eta?, fallback?

An example call and result for ask:

tools/call → result
// 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:

  1. The agent calls request_authorization with { "email", "scope" }.
  2. 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.
  3. The user reads the code and gives it to their agent.
  4. The agent calls verify_authorization with { "email", "code" } and gets an authorization_token.
RuleValue
Code life10 minutes, single use, stored hashed
Code sendsAt most 3 per email per hour, plus per-operator, per-IP and per-workspace daily caps
Verification attemptsAt most 5 per code
TokenOpaque, 256-bit, stored hashed, bound to the email, operator and scopes
Token life1 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.

PostureBehavior
blockRequests for this journey get agents_not_accepted and a pointer to the human channel.
tolerateThe agent can ask, open_case and case_status. Actions always go to a person.
serveThe agent can use every tool the desk offers, inside limits.

Errors

Transport level (HTTP)

CodeHTTPMeaning
signature_invalid401A signature is present but invalid, expired, replayed or unverifiable. Unsigned requests are not an error.
rate_limited429Too many requests. Retry-After is set.

Tool level (MCP result with isError: true)

CodeMeaning
authorization_requiredThe tool needs a user authorization token.
authorization_invalidWrong, expired or out-of-scope token or code.
signature_requiredThis tool needs a verified agent.
agents_not_acceptedPosture is block for this journey.
limit_exceededOver the merchant's limit. Use handoff_to_human.
rate_limitedA tool-level cap was hit, for example code sends.
not_foundUnknown case_id.

Changelog

MIT License, Copyright (c) 2026 DishIs Technologies LLC. Questions or a desk you'd like to connect? hello@chatsupporthq.com