AI coding 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:

• 31 MCP tools that give your AI assistant direct access to the formae agent API — querying resources, deploying infrastructure, updating your IaC codebase from reality, searching the plugin hub, and more.
• 19 skills that teach your assistant proven workflows — from authoring new infrastructure end to end (infer the right plugins, pull version-matched examples, design stacks, simulate, apply) to absorbing out-of-band changes back into your 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

Run /reload-plugins (Claude Code v2.1.116+) to apply the install without restarting your session. On older versions, restart Claude Code instead. 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-author	Front door for authoring new infrastructure — triages intent, infers plugins, dispatches to the focused skills below
/formae-project-init	Scaffold a new forma project with the right layout and config
/formae-deps	Add or remove plugin schema dependencies in a project
/formae-stack-design	Design how resources are grouped into stacks
/formae-apply	Deploy infrastructure (simulate, confirm, apply)
/formae-patch	Targeted infrastructure change without full reconcile
/formae-rename	Rename a resource's label via alias without recreating the cloud object
/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-policy	Set, remove, or inspect TTL and auto-reconcile policies on a stack
/formae-discover	Find unmanaged resources in cloud accounts
/formae-import	Bring unmanaged resources under formae management
/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-plugin-new	Scaffold a new resource plugin from scratch
/formae-plugin-add-resource	Add a resource type to an existing plugin
/formae-config	Switch, list, save, create, delete, compare, view, and edit formae config profiles (drives formae profile; requires formae >= 0.87.0)

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_changes_since_last_reconcile	List changes since last reconcile
extract_resources	Extract resources as PKL code
list_policies	List reusable policies and the stacks they're attached to
search_hub_plugins	Search the live formae plugin hub by keyword or resource type
get_hub_plugin	Get details for a specific hub plugin
list_plugin_examples	List version-matched examples for a hub plugin
get_plugin_example	Fetch a specific example from a hub plugin

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
force_check_ttl	Trigger an immediate TTL expiry sweep across stacks
force_reconcile_stack	Force a one-shot reconcile on a stack with an auto-reconcile policy
create_inline_policy	Plan a TTL or auto-reconcile policy edit on a stack

Profiles (requires formae >= 0.87.0)

Manage named formae environments (endpoint + targets) from your assistant.

Tool	Description
list_profiles	List configuration profiles and which one is active
current_profile	Show the active profile
use_profile	Switch the active profile — global; only on explicit "change my default" requests
save_profile	Snapshot the active profile under a new name
create_profile	Create a new profile from the starter template
delete_profile	Delete a profile (cannot be the active one)
diff_profiles	Compare two profiles (or one against the active)
read_profile	Return a profile's PKL contents
write_profile	Replace a profile's PKL — overwrite-only; refuses the active profile

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

Profile (formae >= 0.87.0): when no environment variables are set, the MCP server reads the agent endpoint from your active formae profile — or from the profile named by a tool's profile argument. Profiles live at ~/.config/formae/profiles/<name>.pkl and are managed with formae profile (or the profile tools above); each looks like:

amends "formae:/Config.pkl"

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

Targeting a specific environment (requires formae >= 0.87.0):

If you manage several formae environments as named profiles, every tool that talks to an agent accepts an optional profile argument that targets one environment for a single call — without changing which profile is active. Your assistant prefers this per-command targeting over switching the active profile with use_profile, because the active profile is shared with your formae command line and any other assistant sessions, so switching it to "set up" one session would redirect the others. Ask it to "check drift in staging" or "apply to prod" and it targets that environment per command; switching your default happens only when you explicitly ask. Use the profile tools above to manage the profiles themselves.

Example workflows

Author new infrastructure from scratch

"I want to deploy a vLLM server on my Kubernetes cluster with formae"

Starting from just a description, the assistant works out whether to create a new project or build in one you already have, adds the formae plugins you need, pulls real examples for them, helps you group resources into stacks, and walks you through simulating before applying — no need to know the forma file layout up front.

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.