# Custom domains your coding agent can add.

Cnamio is documented for machines as carefully as for people: a skill an agent can follow, an MCP server it can call, an OpenAPI document and plain-text docs. Paste one line and review what it wrote.

## Start with one line

Paste this into your AI coding agent, in the project where users should be able to connect a domain:

**English**

```
Add custom domains for my users with Cnamio: read and follow https://cnamio.com/agent-onboarding/SKILL.md. If I don't have a Cnamio account yet, start in the sandbox right away and ask me before signing me up for a free account with my email.
```

**Português**

```
Adicione domínio próprio para os usuários deste app com o Cnamio: leia e siga https://cnamio.com/agent-onboarding/SKILL.md. Se eu ainda não tiver conta no Cnamio, comece já no sandbox e me pergunte antes de criar uma conta gratuita com o meu e-mail.
```

**Español**

```
Agrega dominios propios para los usuarios de esta app con Cnamio: lee y sigue https://cnamio.com/agent-onboarding/SKILL.md. Si todavía no tengo cuenta en Cnamio, empieza ya en el sandbox y pregúntame antes de crear una cuenta gratuita con mi correo.
```

The agent needs your application id and secret in the environment. If you do not have them yet, it can start without them (below), or you can [create a free account](https://cnamio.com/#start) yourself. The skill tells the agent never to invent or hard-code credentials, and never to ask you to paste the secret into the chat.

## No account yet: sandbox now, sign-up by email

An agent can take you from zero to a working integration in one session, without you leaving the editor until the last step:

1. **Sandbox at once.** `POST https://api.cnamio.com/v1/agent/sandbox` (MCP: `start_sandbox`) returns a 30-minute session of a Cnamio test application, with no account and no credentials. The agent runs the check, the connection and the status calls end to end against the sandbox provider: any domain connects, `conflict.` and `pending.` prefixes simulate a record in the way and one that never appears. Nothing real is read or written.
2. **Your free account.** With your email and your agreement to the [Terms](https://cnamio.com/terms) and the [Privacy Policy](https://cnamio.com/privacy), the agent calls `POST https://api.cnamio.com/v1/agent/signup` (MCP: `start_signup`). You receive a link; opening it creates the account, with a test application and a live one on the free plan. Nothing is created before you open it.
3. **You finish it.** In the [dashboard](https://api.cnamio.com/panel) you generate the secret and put `CNAMIO_APPLICATION_ID` and `CNAMIO_SECRET` in your server's environment. The agent switches from the sandbox to your test application, then to the live one.

```
curl -s -X POST https://api.cnamio.com/v1/agent/sandbox
curl -s https://api.cnamio.com/v1/agent/signup -H 'Content-Type: application/json' \
  -d '{"email":"YOUR_EMAIL","consent":true}'
```

Both routes are for agents and their tools: a request from a browser (with an `Origin` header) is refused, and sign-ups and sandbox sessions are limited per address and per email.

## What the skill makes the agent do

1. Decide the DNS records your hosting needs, with an ownership TXT per user.
2. Add the environment variable names to the project, without values.
3. Write the server route that creates a session token, behind your own authentication.
4. Open the connect window from your domain settings page, or use the headless API when there is no user interface.
5. Write the webhook endpoint, verifying the signature over the raw body.
6. Check the integration: a session, a signed test webhook, a real domain lookup.

It carries complete examples for Express, Next.js route handlers and FastAPI, and tells the agent to follow your framework's conventions instead of copying them blindly. Read it yourself at [`/agent-onboarding/SKILL.md`](https://cnamio.com/agent-onboarding/SKILL.md).

## Files for agents

Plain files, no HTML to scrape, readable from any origin:

| File | What it is |
| --- | --- |
| [`/agent-onboarding/SKILL.md`](https://cnamio.com/agent-onboarding/SKILL.md) | The integration skill: step by step, with Node.js and Python examples. |
| [`/llms.txt`](https://cnamio.com/llms.txt) | A short index of everything below, for language models and search agents. |
| [`/llms-full.txt`](https://cnamio.com/llms-full.txt) | Everything below in one file: docs, quickstart, skill, recipes, providers and security. |
| [`/docs.md`](https://cnamio.com/docs.md) | The developer docs in Markdown. Every reading page also has its `.md`: [quickstart](https://cnamio.com/quickstart.md), [agents](https://cnamio.com/agents.md), [providers](https://cnamio.com/providers.md), [security](https://cnamio.com/security.md). |
| [`/recipes/*.md`](https://cnamio.com/recipes/nextjs.md) | Framework recipes: Next.js, Express, Rails, Laravel, Django. |
| [`/agent-onboarding/AGENTS.md`](https://cnamio.com/agent-onboarding/AGENTS.md) | A block to paste into your project's AGENTS.md. |
| [`/openapi.json`](https://cnamio.com/openapi.json) | OpenAPI 3.1: every route, request and response, and the webhook payload. |
| [`/sdk/cnamio.mjs`](https://cnamio.com/sdk/cnamio.mjs) | Server SDK for Node.js 18+, one file, with types in [`cnamio.d.mts`](https://cnamio.com/sdk/cnamio.d.mts). |
| [`/sdk/cnamio.py`](https://cnamio.com/sdk/cnamio.py) | Server SDK for Python 3.9+, standard library only. |

## MCP server

Agents can use Cnamio directly as tools at `https://api.cnamio.com/mcp` (Streamable HTTP). It is listed in the official MCP Registry as `com.cnamio/domains`. The tools behave exactly like the REST routes: same validation, same limits.

| Tool | What it does |
| --- | --- |
| `get_integration_guide` | Returns the integration guide. Needs no credentials. |
| `start_sandbox` | A 30-minute sandbox session, no credentials. The domain tools below take it as `sandboxToken`. |
| `start_signup` | Emails the developer the link that creates their free account. Needs their email and their consent. |
| `check_domain` | Read-only: DNS provider, setup type, connect methods, nameservers and conflicts with existing records. |
| `connect_domain` | Returns the exact records to create and starts watching propagation. |
| `connect_domain_automatic` | Creates the records with the user's provider token, used once. |
| `get_connection_status` | Whether a connection is pending, completed or failed. |
| `recheck_propagation` | Checks again now, at most once every 5 minutes. A finished connection answers 409. |
| `list_connections` | Recent connections of the application. |
| `create_share_link` | A link for whoever manages the DNS (an agency, the IT team): they connect the domains without your keys. |
| `revoke_share_link` | Ends a shareable link at once. |

Add it with no credentials to start: `claude mcp add --transport http cnamio https://api.cnamio.com/mcp`. Three ways to authenticate the domain tools: [OAuth](https://cnamio.com/agents#connectors) (connectors in claude.ai and ChatGPT, and any MCP client that signs in by itself), the application credentials as HTTP Basic, or a session token as `Bearer` plus an `applicationId` header. With Basic, in Claude Code:

```
claude mcp add --transport http cnamio https://api.cnamio.com/mcp \
  --header "Authorization: Basic $(printf '%s' "$CNAMIO_APPLICATION_ID:$CNAMIO_SECRET" | base64 | tr -d '\n')"
```

In clients configured with JSON:

```
{
  "mcpServers": {
    "cnamio": {
      "url": "https://api.cnamio.com/mcp",
      "headers": { "Authorization": "Basic <base64 of applicationId:secret>" }
    }
  }
}
```

**Keep this configuration out of version control.** It carries the application secret.

## Connect in claude.ai or ChatGPT

No secret to paste: the connector signs you in to Cnamio with OAuth 2.1, and you choose which of your applications the assistant may act for.

1. **Claude** (claude.ai, Desktop, mobile): in Settings, Connectors, add a custom connector with the URL `https://api.cnamio.com/mcp`. **ChatGPT**: in Settings, Apps, create an app (developer mode) with the same URL and OAuth authentication. Other MCP clients that support OAuth (Claude Code, Cursor, VS Code) take the same URL with no header.
2. The integration guide works at once. The first time the assistant checks or connects a domain, it asks you to connect: you land on a Cnamio page.
3. Sign in with your account email (we send a link; open it in the same browser), pick the application and look at the permissions, then choose **Authorize**. You go back to the assistant, which carries on.

| Permission | What it allows | Tools |
| --- | --- | --- |
| `domains:read` | See where a domain's DNS is hosted and follow the application's connections. | `check_domain`, `get_connection_status`, `list_connections` |
| `domains:write` | Start connections: manual records, or with the provider token the domain owner gives. Existing records are never deleted. | `connect_domain`, `connect_domain_automatic`, `recheck_propagation` |
| `share_links:write` | Create and revoke connection links for whoever manages the DNS. | `create_share_link`, `revoke_share_link` |

Access tokens last one hour and are renewed by the connector; renewing rotates the refresh token, and a refresh token used twice ends the connection. Pick your **test** application to try it: everything runs in the sandbox and no real DNS is read or changed. To cut access, open the dashboard, **Connected agents**, and revoke it. Discovery for client developers: [`/.well-known/oauth-protected-resource/mcp`](https://api.cnamio.com/.well-known/oauth-protected-resource/mcp) and [`/.well-known/oauth-authorization-server`](https://api.cnamio.com/.well-known/oauth-authorization-server) (PKCE S256, Client ID Metadata Documents and dynamic registration).

### Em português: conectar no claude.ai ou no ChatGPT

Nenhum segredo para colar: o conector faz você entrar no Cnamio por OAuth 2.1, e você escolhe por qual das suas aplicações o assistente pode agir.

1. **Claude** (claude.ai, Desktop, celular): em Configurações, Conectores, adicione um conector personalizado com a URL `https://api.cnamio.com/mcp`. **ChatGPT**: em Configurações, Apps, crie um app (modo de desenvolvedor) com a mesma URL e autenticação OAuth. Outros clientes MCP com OAuth (Claude Code, Cursor, VS Code) usam a mesma URL, sem cabeçalho.
2. O guia de integração funciona na hora. Na primeira vez que o assistente consultar ou conectar um domínio, ele pede para você se conectar e abre uma página do Cnamio.
3. Entre com o e-mail da sua conta (enviamos um link; abra no mesmo navegador), escolha a aplicação, confira as permissões e clique em **Autorizar**. Você volta ao assistente, que continua de onde parou.

Permissões: `domains:read` (ver onde o DNS está e acompanhar as conexões), `domains:write` (iniciar conexões; registros existentes nunca são apagados) e `share_links:write` (links de conexão para quem cuida do DNS). Para testar, escolha a aplicação de **teste**: tudo roda no sandbox. Para cortar o acesso, abra o painel, **Agentes conectados**, e revogue.

### En español: conectar en claude.ai o ChatGPT

Ningún secreto que pegar: el conector te hace entrar a Cnamio con OAuth 2.1, y tú eliges por cuál de tus aplicaciones puede actuar el asistente.

1. **Claude** (claude.ai, Desktop, móvil): en Configuración, Conectores, agrega un conector personalizado con la URL `https://api.cnamio.com/mcp`. **ChatGPT**: en Configuración, Apps, crea una app (modo desarrollador) con la misma URL y autenticación OAuth. Otros clientes MCP con OAuth (Claude Code, Cursor, VS Code) usan la misma URL, sin encabezado.
2. La guía de integración funciona al instante. La primera vez que el asistente consulte o conecte un dominio, te pide conectarte y abre una página de Cnamio.
3. Entra con el correo de tu cuenta (enviamos un enlace; ábrelo en el mismo navegador), elige la aplicación, revisa los permisos y haz clic en **Autorizar**. Vuelves al asistente, que sigue donde estaba.

Permisos: `domains:read` (ver dónde está el DNS y seguir las conexiones), `domains:write` (iniciar conexiones; los registros existentes nunca se borran) y `share_links:write` (enlaces de conexión para quien maneja el DNS). Para probar, elige la aplicación de **prueba**: todo corre en el sandbox. Para cortar el acceso, abre el panel, **Agentes conectados**, y revócalo.

## Headless flow

For agents, CLIs and backends without a user interface, the same connection runs over the API. With the Node.js SDK (Python has the same functions in snake_case):

```
import { Cnamio, recordsForUser } from './lib/cnamio.mjs';

const cnamio = new Cnamio();
const records = recordsForUser({ target: 'customers.yourapp.com', userId, ownershipKey: process.env.CNAMIO_OWNERSHIP_KEY });

// 1. Where is the DNS, and can the records be created with a token?
const check = await cnamio.checkDomain('shop.customer.com', records);

// 2. Create them with the user's provider token, or get the exact records to show.
const job = providerToken && check.connectMethods.includes('api_token')
  ? await cnamio.connectAutomatic('shop.customer.com', records, providerToken, { userId })
  : await cnamio.connect('shop.customer.com', records, { userId });

// 3. Follow it, or wait for the domain.added webhook.
const { connected, status } = await cnamio.status(job.job_id);
```

A `409` means existing records block the connection and nothing was changed: show the conflicts to the user. A `422` means the provider refused the token: fall back to `connect`. Which providers accept a token is on the [providers page](https://cnamio.com/providers).

## A block for your AGENTS.md

So that every agent working in your repository knows how custom domains work there, paste [`/agent-onboarding/AGENTS.md`](https://cnamio.com/agent-onboarding/AGENTS.md) into your `AGENTS.md`, `CLAUDE.md` or editor rules:

```
curl -s https://cnamio.com/agent-onboarding/AGENTS.md >> AGENTS.md
```

Framework recipes with real code: [Next.js](https://cnamio.com/recipes/nextjs.md), [Express](https://cnamio.com/recipes/express.md), [Rails](https://cnamio.com/recipes/rails.md), [Laravel](https://cnamio.com/recipes/laravel.md) and [Django](https://cnamio.com/recipes/django.md).

## Rules we give every agent

- The secret stays on the server. Browsers, and agents acting for end users, get 60-minute session tokens only.
- Never store, log or forward a DNS provider token: pass it straight to the automatic connection.
- Treat the webhook as the source of truth. A browser event can be lost when the user closes the tab.
- Cnamio never deletes DNS records. To retry or change domains, start a new connection.

---

This is the Markdown of https://cnamio.com/agents. Every page for agents: https://cnamio.com/llms.txt
