> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuon.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Operate and build Nuon from LLM clients.

<Note>
  **AI agent** here means an LLM client (Claude Code, Cursor, etc.) driving the control plane. This is not the [install runner](/concepts/runners) in customer clouds.
</Note>

Use an LLM client to read and operate orgs, apps, installs, and workflows, or to scaffold app config from example repos.

<CardGroup cols={2}>
  <Card title="MCP walkthrough" icon="route" href="/guides/agents/mcp-walkthrough">
    Connect Claude Code, Cursor, or Amp and run your first calls.
  </Card>

  <Card title="Tools" icon="wrench" href="/guides/agents/tools">
    Read and write tools exposed on the control plane.
  </Card>

  <Card title="Sample queries" icon="comments" href="/guides/agents/sample-queries">
    Prompts to paste into your client after MCP is connected.
  </Card>

  <Card title="AI and app building" icon="code" href="/guides/agents/ai-and-apps">
    Generate Nuon app config with Claude Code, Gemini, Amp, and skills.
  </Card>
</CardGroup>

## Prerequisites

```bash theme={null}
nuon auth login
nuon orgs select
```

`nuon agents context` prints your auth, selected org/app/install, MCP HTTP URL, 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`. The proxy derives its URL from the configured API hostname (`api.<hostname>` becomes `mcp.<hostname>/mcp`) and registers as `nuon`.

### Setup (stdio)

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add --transport stdio nuon -- nuon agents mcp --allow-writes
  ```

  ```bash Amp theme={null}
  amp mcp add nuon -- nuon agents mcp --allow-writes

  # this workspace only
  amp mcp add nuon --workspace -- nuon agents mcp --allow-writes
  ```

  ```json Cursor theme={null}
  {
    "mcpServers": {
      "nuon": {
        "command": "nuon",
        "args": ["agents", "mcp", "--allow-writes"]
      }
    }
  }
  ```
</CodeGroup>

Cursor has no `mcp add`. Save the JSON as `~/.cursor/mcp.json` or project `.cursor/mcp.json`, then `agent mcp enable nuon`.

Examples include `--allow-writes` so mutating tools are available. Your token must have create permission. 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`).

### Override the server

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`). To point somewhere else, pass `--url`; to change the name in the client's MCP list, pass `--name`. Put those flags on the command the client runs:

```bash theme={null}
nuon agents mcp --allow-writes --url https://mcp.example.com/mcp --name nuon-example
claude mcp add --transport stdio nuon -- nuon agents mcp --allow-writes --url https://mcp.example.com/mcp --name nuon-example
amp mcp add nuon -- nuon agents mcp --allow-writes --url https://mcp.example.com/mcp --name nuon-example
```

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 (Cursor: in `args`).

Run `nuon agents context` to confirm which MCP URL resolves before registering.

## Related CLI flags

These apply to `nuon` commands, not MCP tools:

| Flag             | Purpose                                                   |
| ---------------- | --------------------------------------------------------- |
| `--output agent` | Single JSON envelope on stdout (`{"ok":true,"data":...}`) |
| `--read-only`    | Block mutating CLI commands (exit 2)                      |

See [CLI commands](/cli-commands) for the full reference.