# AI agent integration

Source: https://docs.settlemint.com/docs/developer-guides/cli/ai-agents
Use the DALP CLI with AI coding agents through shell commands, MCP tools, and generated skill files.



The DALP CLI is the supported interface for AI coding agents. Agents can run `dalp` commands directly, call DALP through MCP tools, or read generated skill files before a run starts. In every mode, each command uses the authenticated CLI session, the active organisation, and the same DALP permission checks as a manual operator.

<Callout type="info" title="For operator guidance">
  For operator guidance, read the [AI assistants overview](/docs/user-guides/ai-agents/overview). This page is for
  developers wiring the CLI into agent workspaces.
</Callout>

## Integration modes [#integration-modes]

| Mode            | Best fit                                                                    | DALP command surface                                                      |
| --------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Shell execution | Claude Code, Codex, OpenCode, CI agents, and any assistant with a terminal. | The agent runs `dalp` commands and parses `--format json` output.         |
| MCP server      | Assistants that support Model Context Protocol and typed tool calls.        | Register with `dalp mcp add`; the CLI exposes DALP commands as MCP tools. |
| Skill files     | Assistants that discover Markdown command guides.                           | Install skills with `dalp skills add`; list them with `dalp skills list`. |

Use shell execution for transparent commands in logs. Use MCP when the assistant supports typed tool calls and shell parsing would add risk. Use skills for local command guidance before the agent writes or runs commands.

## Set up a development workspace [#set-up-a-development-workspace]

### 1. Install and authenticate [#1-install-and-authenticate]

```bash
npm install -g @settlemint/dalp-cli
dalp login --url https://your-platform.example.com
```

Check the authenticated account before starting the agent:

```bash
dalp whoami --format json
```

### 2. Set the organisation context [#2-set-the-organisation-context]

If your account can access more than one organisation, list the organisations and switch explicitly.

```bash
dalp auth org-list --format json
dalp auth org-switch <organizationId> --format json
```

`dalp auth org-switch` requires an organisation ID. Do not rely on an agent to guess the target organisation from natural language.

### 3. Prefer JSON output for shell agents [#3-prefer-json-output-for-shell-agents]

```bash
dalp config set format json
```

Agents should parse JSON fields rather than terminal tables. For one-off commands, you can also pass `--format json` directly.

### 4. Register MCP and skills when supported [#4-register-mcp-and-skills-when-supported]

```bash
# Register the CLI as an MCP server for supported local agents.
dalp mcp add

# Install generated DALP skill files for agent discovery.
dalp skills add

# Confirm the installed DALP skills.
dalp skills list
```

`dalp mcp` and `dalp skills` are local setup commands. They can run before authentication, but DALP platform operations still require a valid login and the required roles.

## MCP server integration [#mcp-server-integration]

The DALP CLI includes a built-in MCP registration command:

```bash
dalp mcp add
```

Use this as the default setup path. The CLI registers itself as an MCP server for supported local agents. After registration, DALP commands appear as assistant tools.

If you maintain MCP configuration manually, the server command is the DALP CLI in MCP mode:

```json
{
  "mcpServers": {
    "dalp": {
      "command": "dalp",
      "args": ["--mcp"]
    }
  }
}
```

Keep authentication in the CLI session or approved environment configuration. Do not put API keys, private keys, or customer secrets in the MCP configuration file.

## Skill integration [#skill-integration]

The CLI can sync generated skill files for agents that read local Markdown instructions.

```bash
dalp skills add
dalp skills list
```

Skills document commands, arguments, options, output format, and examples from CLI metadata. They are guidance for the assistant, not a security boundary.

You can also inspect machine-readable command metadata directly:

```bash
# LLM-readable command manifest
dalp --llms

# JSON Schema for command metadata
dalp --schema
```

## Safe agent patterns [#safe-agent-patterns]

### Inspect before mutate [#inspect-before-mutate]

Ask the agent to query current state first, then propose the exact mutation command for review.

```bash
# 1. Inspect the token.
dalp tokens read <tokenAddress> --format json

# 2. Inspect account roles before asking the agent to prepare privileged actions.
dalp system access-manager roles-list --format json
```

### Make retries idempotent [#make-retries-idempotent]

Use list-before-create or read-before-update patterns. Agents should not retry a mutation blindly after a timeout.

```bash
existing=$(dalp tokens list --format json | jq '.data[]? | select(.symbol == "MTK")')
if [ -z "$existing" ]; then
  dalp tokens create --type equity --name "My Token" --symbol MTK --decimals 18 --countryCode 840 --format json
fi
```

### Preserve organisation scope [#preserve-organisation-scope]

Pin the organisation at the start of the run and include it in the agent's working notes.

```bash
dalp auth org-list --format json
dalp auth org-switch <organizationId> --format json
dalp whoami --format json
```

### Handle structured errors [#handle-structured-errors]

Agents should check exit codes and read the structured error body before retrying or escalating.

```bash
result=$(dalp tokens read <tokenAddress> --format json 2>&1) || {
  echo "$result" | jq -r '.message // .error // .'
  exit 1
}
```

## Security considerations [#security-considerations]

* Agents inherit the authenticated CLI account. Limit that account with DALP roles instead of relying on prompt instructions.
* Operations are scoped to the active organisation. Switch explicitly with `dalp auth org-switch <organizationId>`.
* `dalp mcp add` and `dalp skills add` configure the local agent environment; they do not grant platform access by themselves.
* Keep credentials in the CLI-supported login flow or approved environment configuration. Do not paste secrets into agent prompts, skill files, or MCP JSON.
* Require a human review step for privileged operations such as minting, pausing, role changes, compliance changes, and identity approval.
* Store operational evidence from DALP command output and platform records, not from the assistant's narrative summary alone.

## Command checks [#command-checks]

Use these commands to verify the agent workspace before a DALP run:

```bash
dalp --version
dalp whoami --format json
dalp auth org-list --format json
dalp system access-manager roles-list --format json
dalp mcp --help
dalp skills --help
```

## Next steps [#next-steps]

* Use the [command reference](/docs/developer-guides/cli/command-reference) to confirm command names and options.
* Read [CLI scripting](/docs/developer-guides/cli/scripting) for shell automation patterns.
* Review the [AI assistants overview](/docs/user-guides/ai-agents/overview) for operator-facing controls and usage examples.