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

# Agent Mode

> Drive Fjall from an AI coding agent to deploy AWS infrastructure. SKILL + CLI is the primary path, the MCP server a secondary option.

Fjall offers two ways for an AI agent to drive the CLI. Pick by host capability. They are not equivalent.

## Two surfaces

| Surface                                                                    | Status                            | Best for                                                                                                       |
| -------------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **SKILL + CLI** (the recipe loaded from `~/.claude/skills/fjall/SKILL.md`) | **Production-ready** (primary)    | Claude Code, and any host that loads SKILL files                                                               |
| **MCP server** (`@fjall/mcp`, binary `fjall-mcp`)                          | **Secondary** (narrower coverage) | Claude Desktop, Cursor, Cline, Continue, Zed. Hosts that speak the Model Context Protocol but lack SKILL files |

The **SKILL + CLI path** is what every onboarding flow ships against. The agent reads recipes from `SKILL.md` and shells out to `fjall …` subcommands, getting back TOON-formatted, masked, exit-coded output. A single `--agent` flag flips every command into this output mode.

The **MCP server** is a thin transport wrapper that exposes a subset of CLI commands as MCP tools. It exists because some hosts cannot load skill files. Coverage is intentionally tighter than the SKILL surface.

## When to pick which

* **Claude Code** uses SKILL. Run `fjall agent install-skill` to install the recipe.
* **Anything else** uses MCP. Configure `fjall-mcp` in your client's MCP server list. If your host later grows SKILL support, switch. The SKILL path is faster, more thoroughly tested, and gets new flows first.

## SKILL + CLI quick start

```bash theme={null}
# Install the recipe into your agent's config
fjall agent install-skill

# Verify the recipe was written (Claude Code default)
ls ~/.claude/skills/fjall/SKILL.md
```

The agent loads Fjall context on session start and follows the plan, review, apply recipe for app scaffolding (preview with `--dry-run`, review the TOON output, apply, deploy).

See [Session Hooks](/cli/agent-mode/session-hooks) for the ambient context the SKILL relies on.

## MCP server quick start

<Steps>
  <Step title="Install the MCP package">
    ```bash theme={null}
    npm install -g @fjall/mcp
    ```
  </Step>

  <Step title="Register the server with your host">
    For Claude Desktop, edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "fjall": {
          "command": "fjall-mcp"
        }
      }
    }
    ```
  </Step>

  <Step title="Restart your host">
    The production tools, the `scaffold_from_repo` prompt, and the `fjall://plans/{planId}` resource scheme appear after restart.
  </Step>
</Steps>

## Production tools (MCP)

| Tool                   | Annotation        | Purpose                                                   |
| ---------------------- | ----------------- | --------------------------------------------------------- |
| `create_organisation`  | `destructiveHint` | Scaffold organisation and open the AWS OIDC trust flow    |
| `add_resource`         | `destructiveHint` | Add storage, cache, queue, or database to an application  |
| `deploy`               | `destructiveHint` | Deploy infrastructure and code to AWS                     |
| `destroy`              | `destructiveHint` | Tear down deployed infrastructure                         |
| `list_resources`       | `readOnlyHint`    | List organisations and applications                       |
| `detect_app_framework` | `readOnlyHint`    | Inspect a repo for framework, Dockerfile, and port        |
| `plan_app_scaffold`    | `readOnlyHint`    | Compute a scaffold plan, returns `fjall://plans/{planId}` |
| `apply_app_scaffold`   | `destructiveHint` | Apply a planned scaffold and stream progress              |

<Note>
  The MCP surface also registers a `manage_profile` tool, but it shells out to a `fjall profile` command that no longer exists, so it does not work. Fjall has no manual profile step. AWS profiles are derived automatically from your organisation config, and the active deployment account is selected with `fjall target set <name>`. See [Understanding Profiles](/deployment/understanding-profiles).
</Note>

The `detect → plan → apply` trio is the canonical scaffold flow. Agents call them in order so the host can render the intermediate plan resource before any writes.

The plan resource URI is `fjall://plans/{planToken}`, where `planToken` is an HMAC-SHA256 token bound to the plan id, expiry, and a per-process server secret. `apply_app_scaffold` and the resource read verify the token before any lookup, surfacing `INVALID_PLAN_TOKEN` (tampered or malformed) or `EXPIRED_PLAN_TOKEN` (past the 15-minute TTL). Server restart invalidates outstanding plans by design.

## Authentication

Both surfaces use the same `~/.fjall/auth.json` token store. Run `fjall login` once before the agent's first call.

| Surface         | Missing-auth behaviour                                                                                                                        |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **SKILL + CLI** | Resolves missing auth inline via the device-code flow (it pauses, you complete the browser step, the agent continues).                        |
| **MCP server**  | Returns an `AUTHENTICATION_REQUIRED` frame. Log in out-of-band, then retry. The protocol stream cannot be interrupted by interactive prompts. |

## Next Steps

<CardGroup cols={2}>
  <Card title="Session Hooks" icon="link" href="/cli/agent-mode/session-hooks">
    Configure the ambient context the SKILL loads on session start.
  </Card>

  <Card title="fjall login" icon="key" href="/cli/login">
    Authenticate the CLI before the agent's first call.
  </Card>

  <Card title="Understanding Profiles" icon="user-gear" href="/deployment/understanding-profiles">
    See how AWS profiles are derived and how `fjall target` selects the deploy account.
  </Card>

  <Card title="fjall deploy" icon="rocket" href="/cli/deploy">
    Deploy applications and infrastructure to AWS.
  </Card>
</CardGroup>