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

# Agent setup

# Set up Duraton for this project

You are an AI coding agent. Set up Duraton in the current project by completing every step below
**yourself, running the commands directly**. Do not ask the user to run them, and do not just print
instructions. Work through the steps in order.

Duraton is where people build and sell AI agents, no code required; this setup is for the code
path. It gives you two things: the ability to **search the Duraton docs**, and the ability to
**drive a user's Duraton runs, events, and approvals** through tools.

***

## Step 1 - Detect which agent you are

Figure out which coding agent is running you, because the commands differ:

* **Claude Code** - you have a `claude` CLI and read `CLAUDE.md`.
* **Codex** - you have a `codex` CLI and read `AGENTS.md`.
* **Cursor** - configuration lives in `.cursor/mcp.json` and `.cursor/rules/`.
* **Windsurf** - configuration lives in `~/.codeium/windsurf/mcp_config.json`.
* **VS Code** - MCP servers live in `.vscode/mcp.json` under a `servers` key.
* **Anything else** - you have some `mcpServers` (or `servers`) config file you can edit.

Pick the matching branch in each step below. If you cannot tell, use the generic "Config file"
form.

***

## Step 2 - Add the Duraton docs MCP (so you can search the docs)

This is a read-only server that lets you search and fetch Duraton documentation on demand.

**Claude Code:**

```sh theme={null}
claude mcp add --transport http duraton-docs https://docs.duraton.ai/mcp
```

**Codex:**

```sh theme={null}
codex mcp add duraton-docs --url https://docs.duraton.ai/mcp
```

**Cursor / Windsurf / VS Code / other** - add this server to the MCP config file. Use the shape your
client expects:

```json theme={null}
{
  "mcpServers": {
    "duraton-docs": {
      "type": "http",
      "url": "https://docs.duraton.ai/mcp"
    }
  }
}
```

(VS Code nests servers under a `servers` key instead of `mcpServers`. Windsurf names the field
`serverUrl`.)

***

## Step 3 - Add the Duraton product MCP (so you can drive runs and events)

This server lets you list and control runs, trigger events, and manage approvals. It
uses OAuth - no key goes in the config.

There are two URL forms:

* **Bare URL** `https://mcp.duraton.ai` - connects your whole workspace: use `list_projects` and
  `select_project` to switch, and `create_project` to add one (e.g. dev, staging, prod). One active
  project at a time. Best for interactive use.
* **Per-project URL** `https://mcp.duraton.ai/YOUR_PROJECT_ID` - pinned to exactly one project.
  Best for a repo that always targets the same project, and for CI. The user finds the project id in
  the Duraton console.

Default to the **bare URL** unless the user has told you which project id to pin.

**Claude Code:**

```sh theme={null}
claude mcp add --transport http duraton https://mcp.duraton.ai
```

Then run `/mcp` in the session and follow the OAuth flow to authorize. To pin one project instead,
use `https://mcp.duraton.ai/YOUR_PROJECT_ID`.

**Codex:**

```sh theme={null}
codex mcp add duraton --url https://mcp.duraton.ai
codex mcp login duraton
```

**Cursor / Windsurf / VS Code / other** - add the server to the MCP config file:

```json theme={null}
{
  "mcpServers": {
    "duraton": {
      "type": "http",
      "url": "https://mcp.duraton.ai"
    }
  }
}
```

Use `https://mcp.duraton.ai/YOUR_PROJECT_ID` in place of the bare URL to pin a single project.

***

## Step 4 - Install the Duraton agent rules

Fetch the Duraton rules file and save it where your agent reads project rules, so you have Duraton's
core concepts on hand:

```sh theme={null}
curl -fsSL https://docs.duraton.ai/agent-rules.md
```

Save the contents to the right place for your agent:

* **Claude Code** - append it to `./CLAUDE.md`, or save it as `./duraton-rules.md` and add an
  `@duraton-rules.md` import line to `CLAUDE.md`.
* **Codex** - append it to `./AGENTS.md`.
* **Cursor** - save it as `.cursor/rules/duraton.mdc`.
* **Windsurf** - save it to your rules directory (e.g. `.windsurf/rules/duraton.md`).
* **VS Code / other** - save it to your agent's steering/rules path.

***

## Step 5 - Authenticate

OAuth for the Duraton product MCP triggers automatically the first time you call one of its tools
(in Claude Code you can also run `/mcp`). A browser opens; the **user** completes sign-in and, on
the bare URL, picks the Workspace and Project. You do not handle credentials - just trigger the flow
and let the user finish it.

To confirm everything works, call a read-only tool such as `list_runs` once authorized.

***

## Guardrails

* **Never ask the user for, or store, a Duraton secret key.** Secret keys look like
  `dtn_live_...`. They are issued by the user in the Duraton console under **API Keys** and are set
  as the `DURATON_API_KEY` environment variable **only when wiring a runner** (the process that
  executes workflows) - never for MCP setup, which uses OAuth.
* **Grant the least privilege the task needs.** Use read-only access when you only inspect runs; ask
  for write access only when you must trigger events or control runs.
* **Prefer a per-project URL for anything unattended** (CI, a repo pinned to one project) so the
  project can never drift; use the bare URL for interactive work.
* **Respect the user stopping the setup.** If the user declines a step or aborts, stop - do not work
  around it.