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

​
Two surfaces

SurfaceStatusBest 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

1

Install the MCP package

npm install -g @fjall/mcp
2

Register the server with your host

For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "fjall": {
      "command": "fjall-mcp"
    }
  }
}
3

Restart your host

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

​
Production tools (MCP)

ToolAnnotationPurpose
create_organisationdestructiveHintScaffold organisation and open the AWS OIDC trust flow
add_resourcedestructiveHintAdd storage, cache, queue, or database to an application
deploydestructiveHintDeploy infrastructure and code to AWS
destroydestructiveHintTear down deployed infrastructure
list_resourcesreadOnlyHintList organisations and applications
detect_app_frameworkreadOnlyHintInspect a repo for framework, Dockerfile, and port
plan_app_scaffoldreadOnlyHintCompute a scaffold plan, returns fjall://plans/{planId}
apply_app_scaffolddestructiveHintApply 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.
SurfaceMissing-auth behaviour
SKILL + CLIResolves missing auth inline via the device-code flow (it pauses, you complete the browser step, the agent continues).
MCP serverReturns 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.