# AI agent integration

Source: https://docs.settlemint.com/docs/developers/developer-guides/cli/ai-agents
Set up the DALP CLI for shell-based agents, MCP tool calls, 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.

Before you give an assistant a DALP task, install the CLI, authenticate it, pin the organisation, and choose the integration mode that matches the runtime. Shell execution is easiest to audit. MCP is safer when typed tool calls are available. Skill files teach the command surface before work starts.

<Callout type="info" title="For operator guidance">
  For operator guidance, read the [AI assistants overview](/docs/operators/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                                                      | Before the run starts                                         |
| --------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| Shell execution | CI jobs and any approved assistant runtime with terminal access.       | The agent runs `dalp` commands and parses `--format json` output.         | Set JSON output and confirm `dalp whoami --format json`.      |
| MCP server      | Local agents that support Model Context Protocol and typed tool calls. | Register with `dalp mcp add`; the CLI exposes DALP commands as MCP tools. | Register the server and keep credentials out of the settings. |
| Skill files     | Agent runtimes that discover Markdown command guides.                  | Install skills with `dalp skills add`; list them with `dalp skills list`. | Refresh skills after CLI upgrades or command-surface changes. |

Use shell execution for transparent logs. Use MCP when typed tool calls reduce parsing risk. Use skills for local command guidance while the agent prepares work. You can combine all three modes in the same workspace: skills explain the CLI surface, MCP exposes tools, and shell commands remain available for explicit checks.

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

Set up the workspace in this order so the assistant can show the starting state before any DALP operation. The sequence also gives reviewers predictable evidence: CLI version, authenticated account, selected organisation, and machine-readable output.

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

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

Then check the authenticated account at the start of the run:

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

This gives the assistant a concrete account and tenant record to quote back before any platform operation. If the output is missing or unexpected, fix authentication before continuing.

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

If your account can access more than one tenant, list the available 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, then exposes DALP commands as assistant tools.

If you maintain MCP settings manually, run 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 settings 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 use CLI metadata to describe arguments, options, output formats, and examples. They guide the assistant; they are not a security boundary.

You can inspect the same metadata directly when you want to review the generated guidance:

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

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

Use this output when you want to check names, options, and examples without opening the full command reference. The manifest helps you review generated guidance before handing over a narrow task.

## 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
}
```

If a check fails, stop the run and fix the setup. Do not continue from guessed state or ask the agent to infer missing organisation, role, or token information.

## 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
```

| Check                       | Confirms                                                         |
| --------------------------- | ---------------------------------------------------------------- |
| `dalp --version`            | The workspace uses the expected CLI installation.                |
| `dalp whoami --format json` | The agent can read the active account and organisation as JSON.  |
| `dalp auth org-list`        | The operator can select the intended organisation by ID.         |
| `dalp mcp --help`           | MCP registration is available in the local CLI.                  |
| `dalp skills --help`        | Generated skill-file installation is available in the local CLI. |

## Next steps [#next-steps]

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