Start with one line
Paste this into your AI coding agent, in the project where users should be able to connect a domain:
Read and follow https://cnamio.com/agent-onboarding/SKILL.md to let users of this app connect their own domain.
The agent needs your application id and secret in the environment. If you do not have them yet, create a free account: the test application lets the agent run the whole flow against a simulated provider before it touches a real domain. The skill tells the agent to ask you for them and never to invent or hard-code them.
What the skill makes the agent do
- Decide the DNS records your hosting needs, with an ownership TXT per user.
- Add the environment variable names to the project, without values.
- Write the server route that creates a session token, behind your own authentication.
- Open the connect window from your domain settings page, or use the headless API when there is no user interface.
- Write the webhook endpoint, verifying the signature over the raw body.
- 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.
Files for agents
Plain files, no HTML to scrape, readable from any origin:
| File | What it is |
|---|---|
/agent-onboarding/SKILL.md | The integration skill: step by step, with Node.js and Python examples. |
/llms.txt | A short index of everything below, for language models and search agents. |
/docs.md | The developer docs in Markdown. The same text is served as plain text at /llms-full.txt. |
/openapi.json | OpenAPI 3.1: every route, request and response, and the webhook payload. |
/sdk/cnamio.mjs | Server SDK for Node.js 18+, one file, with types in cnamio.d.mts. |
/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. |
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. |
Authenticate with the application credentials as HTTP Basic, or with a session token as Bearer plus an applicationId header. 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.
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.
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.