AI Assistants

formae ships an MCP server and a set of skills that teach AI coding assistants how to manage infrastructure through formae. This means you can deploy, query, and manage cloud resources through natural conversation with your AI assistant.

What you get

The formae MCP plugin provides:

  • 15 MCP tools that give your AI assistant direct access to the formae agent API — querying resources, deploying infrastructure, easily updating your IaC codebase from reality, and more.
  • 13 skills that teach your assistant proven workflows — like applying infrastructure changes safely (simulate first, confirm, then apply) or absorbing out-of-band and incremental changes into your own IaC codebase.

Prerequisites

  • Go 1.25+
  • A running formae agent (formae agent start)

Installation

Claude Code (via Plugin Marketplace)

Register the marketplace:

/plugin marketplace add platform-engineering-labs/formae-marketplace

Install the plugin:

/plugin install formae-mcp@formae-marketplace

Restart Claude Code for the plugin to take effect. The MCP server binary is built automatically on first use.

Verify by asking Claude to run /formae-status.

Claude Code (manual)

If you prefer not to use the marketplace:

  1. Clone the repo:

    git clone https://github.com/platform-engineering-labs/formae-mcp.git \
  ~/.claude/plugins/formae-mcp

  2. Start Claude Code with the plugin directory:

    claude --plugin-dir ~/.claude/plugins/formae-mcp

Available skills

Skills are workflows that your AI assistant follows when you ask it to perform infrastructure tasks. They enforce safe practices like simulating before applying, and asking for confirmation before destructive operations.

Skill Description
/formae-status Check running commands, deployment progress, and failures
/formae-stacks View infrastructure stacks and resource counts
/formae-resources Query resources by type, stack, label, or management status
/formae-targets List cloud targets and configured regions
/formae-plugins List installed plugins and supported resource types
/formae-apply Deploy infrastructure (simulate, confirm, apply)
/formae-patch Targeted infrastructure change without full reconcile
/formae-destroy Tear down resources, stacks, or environments
/formae-fix-code-drift Detect and absorb out-of-band and incremental changes into your IaC codebase
/formae-discover Find unmanaged resources in cloud accounts
/formae-import Bring unmanaged resources under formae management
/formae-plugin-new Scaffold a new resource plugin from scratch
/formae-plugin-add-resource Add a resource type to an existing plugin

Available MCP tools

Read-only

Tool Description
list_resources Query resources with optional filters
list_stacks Retrieve all stacks
list_targets Query configured cloud targets
get_command_status Get status of a specific command
list_commands List commands with optional filters
get_agent_stats Retrieve agent statistics
check_health Health check for the agent
list_plugins List active plugins
list_changes_since_last_reconcile List changes since last reconcile
extract_resources Extract resources as PKL code

Mutation

Tool Description
apply_forma Deploy or update infrastructure
destroy_forma Remove infrastructure by file or query
cancel_commands Cancel running commands
force_sync Trigger immediate resource synchronization
force_discover Trigger immediate resource discovery

Configuration

By default, the MCP server connects to the formae agent at http://localhost:49684. To override this:

Environment variables (highest precedence):

export FORMAE_AGENT_URL=http://my-agent-host
export FORMAE_AGENT_PORT=8080

Config file (~/.config/formae/formae.conf.pkl):

amends "formae:/Config.pkl"

cli {
  api {
    url = "http://my-agent-host"
    port = 8080
  }
}

Example workflows

Deploy infrastructure

"Apply my VPC forma file at infra/vpc.pkl"

The assistant will simulate the deployment first, show you what will be created, ask for confirmation, and then apply.

Check for drift in your IaC codebase

"Has anything changed in my production stack since the last reconcile?"

The assistant will query the agent, cross-reference with your IaC code, and present only true delta — changes not yet reflected in your codebase.

Absorb out-of-band and incremental changes

"Absorb out-of-band changes into my IaC code"

The assistant will extract the current state, edit your PKL files to match, and verify with a simulation that the code is now in sync.

Build a new plugin

"Build a Cloudflare plugin for formae"

The assistant will research the Cloudflare API, suggest resource types organized in implementation waves, scaffold the plugin, and TDD through each CRUD operation following the plugin SDK tutorial.