AI assistants

The formae MCP plugin has been renamed from formae-mcp to formae. If you installed formae-mcp, uninstall it and install formae before continuing. Follow the migration steps.

formae ships an MCP server and a set of skills that teach AI coding assistants how to manage infrastructure. Once connected, you can deploy, query, and change cloud resources through natural conversation.

Release notes for the MCP server live in its CHANGELOG in the formae-mcp repository, not in these docs.

What you get

MCP tools that give your assistant access to inventory, command history, schema information, simulation and deployment.
Skills that guide stack design, Pkl authoring, resolution of out-of-band changes, and maintaining a source project when you choose to have one.

Both pieces matter. The tools are the API access; the skills are the workflows that use them safely (simulate before applying, confirm before destroying). A client with skills but no MCP server registered will fail on every tool call.

Prerequisites

git and curl
A running formae agent (formae agent start) and a formae profile pointing at it

You do not need a Go toolchain. The MCP server and a matched formae binary are downloaded as prebuilt artifacts into ~/.formae-ai/opt on first launch. Nothing is compiled on your machine.

Migrate from formae-mcp

If you previously installed the plugin as formae-mcp, uninstall that entry and install formae. Use the marketplace where you installed the old plugin if it has a different name from formae-marketplace.

Claude Code
Codex
Manual MCP configuration

/plugin uninstall formae-mcp@formae-marketplace
/plugin marketplace add platform-engineering-labs/formae-marketplace
/plugin install formae@formae-marketplace

Run /reload-plugins, or restart Claude Code if your version does not support it.

codex plugin remove formae-mcp@formae-marketplace
codex plugin marketplace add platform-engineering-labs/formae-marketplace
codex plugin add formae@formae-marketplace

Start a new Codex session after installing.

Remove the old formae-mcp server registration from your assistant’s MCP configuration and follow the installation instructions for your assistant to register formae. Remove any old skills registration before linking the current skills.

Check your assistant’s installed plugins or MCP servers: formae should be present and the old formae-mcp entry should be gone. Then ask your assistant to check formae status. The source repository is still named formae-mcp; GitHub URLs using that name remain correct.

Install

Claude Code
Codex
OpenCode
Cursor
Other MCP clients

Claude Code has first-class support through the plugin marketplace. The MCP server is registered for you, and on first use it downloads a prebuilt server and a matched formae binary into ~/.formae-ai/opt.Register the marketplace:

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

Install the plugin:

/plugin install formae@formae-marketplace

Run /reload-plugins (Claude Code v2.1.116+) to apply without restarting. On older versions, restart Claude Code.Verify: ask Claude to run /formae-status. You should get live agent status back, not an error.

Manual install (without the marketplace)

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

Codex (a recent CLI, verified with 0.148.0) installs plugins from a marketplace the same way Claude Code does. Register the marketplace, then install the plugin:

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

No clone, no symlink, no editing config.toml. The skills and the MCP server both come with the plugin. The first session after install downloads the prebuilt server and a matched formae binary into ~/.formae-ai/opt; later sessions start instantly.Verify: codex plugin list should show formae installed. Then start a session and ask it to check formae status, or search the plugin hub, and confirm a real tool call returns data, not just that the skill loaded.For older Codex versions without plugin marketplace support, see the manual install (clone + symlink + config.toml) documented in .codex/INSTALL.md.

Clone the repo (it carries the skills and the launcher):

git clone https://github.com/platform-engineering-labs/formae-mcp.git \
  ~/.config/opencode/formae
mkdir -p ~/.config/opencode/skills
ln -s ~/.config/opencode/formae/skills ~/.config/opencode/skills/formae

Register the server in opencode.json, pointing the command at the launcher script (use an absolute path). It downloads the prebuilt server and a matched formae binary on first run:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "formae": {
      "type": "local",
      "command": ["/home/you/.config/opencode/formae/scripts/start-mcp.sh"],
      "enabled": true
    }
  }
}

Restart OpenCode.Verify: ask it to check formae status. A working setup returns live agent data.Full details: .opencode/INSTALL.md.

Clone the repo, which carries both the skills and the launcher:

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

Link the skills into the cross-agent location, which Cursor reads (2.4 and later). It is the same link Codex uses, so one symlink serves both:

mkdir -p ~/.agents/skills
ln -s ~/.cursor/formae/skills ~/.agents/skills/formae

Register the server in .cursor/mcp.json (project) or ~/.cursor/mcp.json (global), pointing the command at the launcher (use an absolute path). It downloads the prebuilt server and a matched formae binary on first run:

{
  "mcpServers": {
    "formae": {
      "command": "/home/you/.cursor/formae/scripts/start-mcp.sh"
    }
  }
}

Reload Cursor, then check that the formae server shows as connected in Settings → MCP.

Several skills cross-reference each other as /formae:<name>, which is Claude Code’s syntax and means nothing here. The skills themselves load and work; it is the cross-reference that does not, so ask for the next one by description (“import these resources into my codebase”) rather than by slash command.

Any MCP client can use the formae tools. Clone the repo for the launcher:

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

Then register it using your client’s standard MCP configuration, pointing the command at the launcher (use an absolute path). It downloads the prebuilt server and a matched formae binary on first run. Most clients use this shape:

{
  "mcpServers": {
    "formae": {
      "command": "/home/you/formae-mcp/scripts/start-mcp.sh"
    }
  }
}

The server talks to the formae agent at http://localhost:49684 by default. See Configuration to point it elsewhere.

Configuration

By default the MCP server connects to the formae agent at http://localhost:49684. To point it somewhere else, or to work with more than one environment, use profiles (requires formae >= 0.87.0). The server reads the agent endpoint from your active 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:

amends "formae:/Config.pkl"

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

Targeting a specific environment

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, because the active profile is shared with your formae command line and any other assistant sessions. Ask it to “check out-of-band changes in staging” or “apply to prod” and it targets that environment per command. Switching your default happens only when you explicitly ask.

Choose whether to maintain a codebase

Hosted users can start without a local IaC project. Describe the infrastructure change you want; your assistant authors temporary Pkl from the complete stack’s recorded desired state, simulates it, and asks you to confirm the plan. Pkl remains the schema-checked interface even when you do not keep it on disk. To opt in later, say:

I want to manage my infrastructure in an IaC codebase.

The assistant initializes a project and extracts the managed stacks you select, or uses an existing project. It remembers registered projects locally, separately from connection profiles. Each operation selects a project context for the installation; if several projects could match, it asks which one to use. It does not switch every session to one global active codebase. When working in a project, the assistant keeps that selected project’s source current after shared resolution of out-of-band changes. Without one, the decision is still stored centrally and available to the next session. See Ways to work.

Example workflows

Author new infrastructure from scratch

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

Starting from your description, the assistant finds suitable schemas and examples, helps you group resources into stacks, authors Pkl, and shows a simulation before applying. Hosted users do not need to choose a project directory first. If a maintained project is selected, it works there.

Deploy infrastructure

“Apply my VPC forma file at infra/vpc.pkl”

The assistant simulates the deployment first, shows you what will be created, asks for confirmation, then applies.

Check for out-of-band changes

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

The assistant queries formae and presents the stack changes that require an absorb or revert decision. A local codebase is not required.

Absorb out-of-band changes

“Keep the replica change in production and revert the bucket change”

The assistant simulates the combined resolution, asks for confirmation, and records a reconcile in formae. It then updates the selected project if you maintain one. Other sessions can retrieve the accepted intent directly.

Build a new plugin

“Build a Cloudflare plugin for formae”

The assistant researches the Cloudflare API, suggests resource types organized in implementation waves, scaffolds the plugin, and works through each CRUD operation with tests, following the plugin SDK tutorial.

Available skills

Skills are workflows your assistant follows when you ask for an infrastructure task. They enforce safe practices like simulating before applying and confirming 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 change without a 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`	Resolve out-of-band changes centrally and update an optional selected 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`	Manage formae config profiles (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
`get_command_desired_delta`	Retrieve recorded changes and deletion guidance for updating source after a terminal 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 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

Local authoring context

These tools select and prepare local source without changing cloud resources. A profile chooses the formae installation; a codebase context chooses where the assistant maintains source for the current operation.

Tool	Description
`get_codebase_context`	Resolve registered project candidates for the installation and harness directory, or select no codebase
`list_codebases`	List locally registered projects
`register_codebase`	Register a maintained project and its stack scope
`unregister_codebase`	Remove a local registration without deleting project files
`prepare_authoring`	Retrieve complete desired declarations and render Pkl with dependencies into a disposable directory

The assistant retains temporary authoring files through simulation, submission and retry inspection, then removes them after the outcome is known or an unsent preview is abandoned. An interrupted session can leave those files behind; they are not registered as a maintained project.

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)

Get started

Guides

Concepts

Reference

What you get

Prerequisites

Migrate from formae-mcp

Install

Configuration

Targeting a specific environment

Choose whether to maintain a codebase

Example workflows

Available skills

Available MCP tools

Read-only

Mutation

Local authoring context

Profiles

​What you get

​Prerequisites

​Migrate from formae-mcp

​Install

​Configuration

​Targeting a specific environment

​Choose whether to maintain a codebase

​Example workflows

​Available skills

​Available MCP tools

​Read-only

​Mutation

​Local authoring context

​Profiles

What you get

Prerequisites

Migrate from formae-mcp

Install

Configuration

Targeting a specific environment

Choose whether to maintain a codebase

Example workflows

Available skills

Available MCP tools

Read-only

Mutation

Local authoring context

Profiles