Agents · Skill · MCP · llms.txt · OpenAPI

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:

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

  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.

Files for agents

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

FileWhat it is
/agent-onboarding/SKILL.mdThe integration skill: step by step, with Node.js and Python examples.
/llms.txtA short index of everything below, for language models and search agents.
/docs.mdThe developer docs in Markdown. The same text is served as plain text at /llms-full.txt.
/openapi.jsonOpenAPI 3.1: every route, request and response, and the webhook payload.
/sdk/cnamio.mjsServer SDK for Node.js 18+, one file, with types in cnamio.d.mts.
/sdk/cnamio.pyServer 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.

ToolWhat it does
get_integration_guideReturns the integration guide. Needs no credentials.
check_domainRead-only: DNS provider, setup type, connect methods, nameservers and conflicts with existing records.
connect_domainReturns the exact records to create and starts watching propagation.
connect_domain_automaticCreates the records with the user's provider token, used once.
get_connection_statusWhether a connection is pending, completed or failed.
recheck_propagationChecks again now, at most once every 5 minutes. A finished connection answers 409.
list_connectionsRecent connections of the application.
create_share_linkA link for whoever manages the DNS (an agency, the IT team): they connect the domains without your keys.
revoke_share_linkEnds 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.