Skip to main content
AI agent here means an LLM client (Claude Code, Cursor, etc.) driving the control plane. This is not the install runner in customer clouds.
Use an LLM client to read and operate orgs, apps, installs, and workflows, or to scaffold app config from example repos.

MCP walkthrough

Connect Claude Code, Cursor, or Amp and run your first calls.

Tools

Read and write tools exposed on the control plane.

Sample queries

Prompts to paste into your client after MCP is connected.

AI and app building

Generate Nuon app config with Claude Code, Gemini, Amp, and skills.

​
Prerequisites

Both are required. They write the credentials every setup below reads:
Two commands print this page from the CLI:
  • nuon agents help: for you, the same setup, checked against your own config.
  • nuon agents context: for your agent: auth, selected org/app/install, MCP HTTP URL, tool catalog, and how to read timestamps (UTC/Z, convert to local before naming a day or clock time).

​
Connect

Recommended: register the stdio proxy so the client runs nuon agents mcp --allow-writes. Token and org stay in ~/.nuon, so nothing secret goes into the client config. The proxy derives its URL from the configured API hostname (api.<hostname> becomes mcp.<hostname>/mcp) and registers as nuon.

​
Setup (stdio)

Each client has its own config file, JSON key, and (sometimes) an add command. Check that client’s MCP docs rather than assuming a shared schema. The process every client should spawn is nuon with arguments agents, mcp, and --allow-writes. Examples include --allow-writes so mutating tools are available. That flag only lists write tools; the identity still needs Admin (org_admin), not Read-only. Omit the flag only if you want a read-only proxy. You do not need select_org when the org is already in the CLI config (the stdio proxy sends X-Nuon-Org-ID).

​
Claude Code

Or .mcp.json in a project:

​
Cursor

Cursor has no mcp add. Save this as ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project), then enable it:

​
Amp

Or ~/.config/amp/settings.json (user) / .amp/settings.json (workspace). Amp’s key is amp.mcpServers:

​
Other clients

Use that client’s MCP docs for the file path and JSON key. Point it at the nuon binary with arguments agents, mcp, and --allow-writes.

​
Overriding the MCP URL

The proxy derives its upstream URL from api_url in your CLI config when the hostname starts with api. (https://api.nuon.co → https://mcp.nuon.co/mcp). Pass --url when the MCP URL does not follow from the API URL, for example a self-hosted or Nuon BYOC control plane, or any deployment where the two hostnames differ. To change the name in the client’s MCP list, pass --name. Put those flags on the command the client runs, next to --allow-writes:
For a client configured by file, extra flags go inside args. Use that client’s JSON key (examples above):
A non-default CLI config (nuon -C /path/to/config agents mcp --allow-writes) carries its own token, org, and api_url. Put -C and --allow-writes on the registered command (in args when the client is configured by file). Run nuon agents help or nuon agents context to confirm which MCP URL resolves before registering.