# Agents & MCP

Ingram Domains is built for the case where the caller is an AI agent: no
email confirmations, no browser-only steps, structured errors, explicit
price confirmation, and idempotent mutations everywhere.

## The MCP server

Endpoint: `https://domains.ingram.tech/api/mcp`. It speaks the 2026-07-28 MCP
spec and falls back to stateless Streamable HTTP for 2025-era clients, so one
URL covers both. Authenticate with the same bearer token as REST:

```json
{
  "mcpServers": {
    "ingram-domains": {
      "url": "https://domains.ingram.tech/api/mcp",
      "headers": { "Authorization": "Bearer ingram_live_…" }
    }
  }
}
```

Tools:

| Tool | Scope | Notes |
|---|---|---|
| `check_domain` | public | Availability + retail price |
| `get_tld_pricing` | public | Register/renew/transfer EUR prices |
| `suggest_domain` | read | AI name suggestions, availability-checked and priced |
| `list_domains` | read | The workspace portfolio |
| `register_domain` | write | Requires `confirm_price` — same contract as REST |
| `renew_domain` | write | Requires `confirm_price` |
| `transfer_domain` | write | Requires `confirm_price` + auth code |
| `request_auth_code` | write | Outbound transfer code, emailed to the registrant |
| `delete_domain` | write | Requires explicit confirmation parameters |

Spending tools debit the workspace wallet exactly like REST — quote first
(`check_domain` / `get_tld_pricing`), then confirm the quoted price. A
`price_changed` rejection carries the current price for a re-confirm loop.

## The safety contract (all surfaces)

1. **No implicit spending** — `confirm_price` everywhere; drift rejects.
2. **Idempotent mutations** — `Idempotency-Key` replay returns the stored
   result; timeouts can't double-charge (see [Errors](/docs/errors)).
3. **Free retries after registry failure** — a pay-as-you-go charge whose
   registry action failed stays as wallet credit; the retry doesn't
   re-charge.
4. **Machine-branchable errors** — stable `error` codes with structured
   `details`.
5. **Scoped tokens** — a `read` token cannot spend under any circumstances.

## The in-dashboard assistant

The dashboard ships an assistant (sidebar → **Assistant**) for everything
*non-billable*: DNS records, nameserver switches, security toggles
(registrar lock, auto-renew, WHOIS privacy, DNSSEC), auth codes, availability
and pricing questions, product Q&A, and relaying bug reports to the team. It
deliberately cannot register, renew, transfer, or delete — spending stays in
flows with explicit confirmation.

## Raw docs for LLMs

Every page here is available as plain Markdown at `/docs/raw/<slug>` (e.g.
[`/docs/raw/errors`](/docs/raw/errors)) — curl-able and paste-able into a
context window. The OpenAPI spec at
[`/api/v1/openapi.json`](https://domains.ingram.tech/api/v1/openapi.json) is
the machine-readable REST contract.