Fjall Docs — Deploy Production-Ready AWS Infrastructure in Minutes

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

# 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 for the ambient context the SKILL relies on.

MCP server quick start

Install the MCP package

npm install -g @fjall/mcp

For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fjall": {
      "command": "fjall-mcp"
    }
  }
}

Restart your host

The production tools, the scaffold_from_repo prompt, and the fjall://plans/{planId} resource scheme appear after restart.

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

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.

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

Session Hooks

Configure the ambient context the SKILL loads on session start.

fjall login

Authenticate the CLI before the agent’s first call.

Understanding Profiles

See how AWS profiles are derived and how fjall target selects the deploy account.

fjall deploy

Deploy applications and infrastructure to AWS.

​Two surfaces

​When to pick which

​SKILL + CLI quick start

​MCP server quick start

​Production tools (MCP)

​Authentication

​Next Steps

Session Hooks

fjall login

Understanding Profiles

fjall deploy

Two surfaces

When to pick which

SKILL + CLI quick start

MCP server quick start

Production tools (MCP)

Authentication

Next Steps