Coding agents

Claude Code, Cursor, Codex, Copilot and other coding agents can write scripts against the InfraNest API, and run them. This page is how to set one up so it writes correct code and cannot do damage while it learns.

Two different things are easy to mix up:

• Writing code against the API. The agent needs the docs: point it at /llms.txt or a page's Markdown. See Give an assistant the docs.
• Reading your account while it works. The agent connects to the MCP server, which only reads.

Safe defaults

• Start in the sandbox, with a test token. Your sandbox has sample zones, monitors and a server, and nothing in it reaches a provider or the internet. A test token (in_test_…) cannot touch a live organization even if the agent tries.
• Read-only scopes first. Give the token only the .read scopes the task needs. Add a .write scope when the agent has shown you the change it wants to make.
• Dry-run every DNS change. Add ?dry_run=1 and read the changes it returns before the real request. See Retries and dry runs.
• An Idempotency-Key on every POST, kept when retrying, so a timeout never creates something twice.
• Branch on code, never on message. Error codes are stable; messages may be reworded.
• The token lives in an environment variable, never in code, a commit or a prompt. Tokens expire; a script must handle unauthenticated by stopping, not by retrying.
• Respect Retry-After. The rate limits are per token.

An AGENTS.md snippet

Put this in your repository's AGENTS.md (or CLAUDE.md, .cursor/rules, .github/copilot-instructions.md), so every agent working in it follows the same rules:

## InfraNest API

- Docs: https://developers.infranest.io/llms.txt (index) and https://developers.infranest.io/llms-full.txt (all of it).
  Any page is also Markdown at its address plus `.md`. The API description is https://developers.infranest.io/openapi.json.
- Base address: https://api.infranest.io/api. Send `Authorization: Bearer $INFRANEST_TOKEN` and `Accept: application/json`.
- The token comes from the INFRANEST_TOKEN environment variable. Never print it, log it or write it to a file.
- Use the sandbox organization and a test token (in_test_…) until a person says otherwise.
- Before any DNS change, send it with ?dry_run=1, show the result, and wait for a person to agree.
- Send an Idempotency-Key header (a new UUID) with every POST; reuse it only to retry that same request.
- Branch on the error's `code`, never its `message`. On 429, wait the seconds in Retry-After.
- Never call anything the docs do not list. Tokens and account settings can never be changed through the API.

Prompts that work

• "Read https://developers.infranest.io/recipes/dynamic-dns-from-a-script.md and write a script that keeps home.example.com pointing at this machine's address. Use the sandbox and dry-run first."
• "Using https://developers.infranest.io/reference/monitoring.md, write a GitHub Actions step that pauses monitor $MONITOR_ID for the length of the deploy and resumes it after, even when the deploy fails."
• "List every DNS record in the sandbox that points at 192.0.2.10, then show me the dry run of moving them to 192.0.2.20. Do not apply it."
• "Write a Python function that calls the InfraNest API with retries: honour Retry-After on 429, retry 5xx with backoff, never retry other 4xx, and send the same Idempotency-Key on every retry of a POST."

Give the agent the page that covers the task, not the whole site: it answers better from one relevant page than from everything at once.

Connect it to your account

To let the agent look things up while it works, add the MCP server with a read-only token: Connect with a token. It can never change anything through MCP; the scripts it writes are what change things, with the token you give them.