AI & MCP

Confµgami contains a Model Context Protocol (MCP) server that gives AI coding agents direct access to your definitions and configurations. Instead of guessing the configuration model from file contents, an agent asks the server for the real data, validates its edits with the real validation, and inspects the merged result. The server uses the same parsing and validation engine as the IDE extension and the CLI, so an agent sees exactly what you see.

What the MCP Server Provides

The MCP server exposes the Confµgami workspace to any MCP-capable AI tool, such as Claude Code, GitHub Copilot, OpenCode, or the IntelliJ AI Assistant. Through it, an agent can:

Discover which definitions and configuration files exist in the workspace.
Fetch a definition’s keys, types and bounds, and a starting file for it, before writing a configuration.
Validate configuration and definition files and get diagnostics with file, line, and column.
Format the files it edits to the workspace conventions.
Navigate the model: the instances of a type, what references an element, which file’s value wins, the valid targets of a reference.
Read the fully merged configuration model, the same view your consuming software sees.

The tools operate on the files on disk. The agent edits a file with its normal editing tools, saves it, and then calls the validation tools, there is no separate in-memory state to keep in sync.

Registering the MCP Server

The MCP server is part of the cfu executable, so cfu must be installed and reachable, ideally on your PATH (see the cfu CLI reference). cfu mcp --install writes the launch entry into the MCP configuration file of the chosen client:

$ cfu mcp --install                      # Claude Code and GitHub Copilot, project scope
$ cfu mcp --install --global             # user-level (global) configuration
$ cfu mcp --install claude               # a single client
$ cfu mcp --install claude copilot       # several clients at once

The supported client names are claude (Claude Code), copilot (GitHub Copilot in VS Code), opencode (OpenCode), and intellij (IntelliJ, project scope only). Other servers and settings in the file are preserved. An existing Confµgami entry is reported as updated, with a <file>.bak backup of the previous file, and an entry that already matches is left as it is. Without --global, the registration is written into the current project, which is the recommended scope: the server then starts in the project directory and discovers the workspace from there.

To register the server manually, run cfu mcp --help. It prints a ready-to-paste configuration snippet for each supported client. All snippets launch the same command:

$ cfu mcp --stdio --no-auto-update

You never run this yourself, the AI tool starts and stops it as needed. --no-auto-update keeps the server from replacing its own binary while the AI tool holds it open for a whole session, see Automatic Updates.

Available MCP Tools

Once registered, the MCP server provides the following Confµgami tools:

Tool Purpose

Tool	Purpose
`authoringGuide`	The authoring guide the agent reads before editing a file: syntax, `$` keys, discovery, tool workflow and pitfalls.
`constraintsAuthoringGuide`	The reference of the constraint language the agent reads before writing a definition constraint: expressions, functions, type paths, units, absent values and cost.
`constraintsEvaluate`	What constraint expressions yield and whether a constraint holds, for one configuration instance or every instance of a type, and which values they read, to see why a constraint fires.
`listDefinitions`	The discovered definitions, by the name the other tools take as `defName`.
`listEntityPaths`	Every entity of the merged configuration per CfgSpace, with reference path, `id:` form, type and location: the targets a `ref` can name.
`resolveElement`	What one element is and what connects to it, addressed by file position, entity path or type path: its definition, instances, references, merge sources, the target of a `ref` and what a mixin fills.
`listWorkspaceFiles`	The discovered definition files and, per CfgSpace, the configuration files bound to a definition.
`workspaceOverview`	How discovery sees the workspace: roots, CfgSpaces, the file tree and the skipped folders, like `cfu workspace list`.
`confuSettingsJsonSchema`	The JSON Schema for `.confu` workspace settings files.
`cfgScaffold`	A starting configuration for a definition: every top-level element and the required ones below, defaults filled in, `/* TODO */` where a value is missing.
`cfgValidate`	Validates the configuration files and their definitions, as text and as structured content, the checks of `cfu cfg validate`.
`defValidate`	Validates the definition files, including `.default.def.json5` and `.preconfig.def.json5` files, the checks of `cfu def validate`.
`cfgModelMerged`	The merged configuration model of one CfgSpace as JSON, like `cfu cfg export-merged`. Fails while that space or a definition it binds has errors.
`defExport`	The model of one definition: types, relations, units and bounds, annotation types and global settings, with source positions and documentation on request. Fails for a definition with errors.
`format`	Formats `.cfg`/`.def`/`.confu` files in place with the workspace conventions, an edited file only in its edited lines.

authoringGuide

The authoring guide the agent reads before editing a file: syntax, $ keys, discovery, tool workflow and pitfalls.

constraintsAuthoringGuide

The reference of the constraint language the agent reads before writing a definition constraint: expressions, functions, type paths, units, absent values and cost.

constraintsEvaluate

What constraint expressions yield and whether a constraint holds, for one configuration instance or every instance of a type, and which values they read, to see why a constraint fires.

listDefinitions

The discovered definitions, by the name the other tools take as defName.

listEntityPaths

Every entity of the merged configuration per CfgSpace, with reference path, id: form, type and location: the targets a ref can name.

resolveElement

What one element is and what connects to it, addressed by file position, entity path or type path: its definition, instances, references, merge sources, the target of a ref and what a mixin fills.

listWorkspaceFiles

The discovered definition files and, per CfgSpace, the configuration files bound to a definition.

workspaceOverview

How discovery sees the workspace: roots, CfgSpaces, the file tree and the skipped folders, like cfu workspace list.

confuSettingsJsonSchema

The JSON Schema for .confu workspace settings files.

cfgScaffold

A starting configuration for a definition: every top-level element and the required ones below, defaults filled in, /* TODO */ where a value is missing.

cfgValidate

Validates the configuration files and their definitions, as text and as structured content, the checks of cfu cfg validate.

defValidate

Validates the definition files, including .default.def.json5 and .preconfig.def.json5 files, the checks of cfu def validate.

cfgModelMerged

The merged configuration model of one CfgSpace as JSON, like cfu cfg export-merged. Fails while that space or a definition it binds has errors.

defExport

The model of one definition: types, relations, units and bounds, annotation types and global settings, with source positions and documentation on request. Fails for a definition with errors.

format

Formats .cfg/.def/.confu files in place with the workspace conventions, an edited file only in its edited lines.

Every tool but the two guides and confuSettingsJsonSchema takes a required workspacePath: the workspace root, any file or folder inside it, or a list of start paths like the cfu CLI takes. The server holds no workspace of its own, so several Confµgami workspaces in one repository need no switching: each call names the one it works on. Relative paths in the other arguments resolve against the first workspacePath entry, or its folder when that is a file. The tool descriptions in the MCP client list the remaining arguments.

Tool Results and Errors

A tool that ran and failed answers with a normal tool result marked as an error, carrying its message or diagnostics as text.

The two validation tools report twice: the human report as the text of the result, and the same findings as structured content, with the valid flag, the counts per severity and one object per diagnostic with file, position, severity and message, the fields of cfu cfg validate --output-format json. A result notes unsaved editor changes to the files it read, it is then based on their last saved version.

Built-In Instructions

The server ships its instructions for Confµgami, which MCP-capable tools inject into the agent’s context automatically: the file kinds, the tool workflow and the order to read the authoringGuide before editing a file. Clients cut server instructions short, so the guide holds the rest: how a configuration binds to a definition, workspace discovery and .confu settings, the authoring rules, and the common pitfalls.

No extra skill, rules file, or custom prompt is required to teach the agent Confµgami. Registering the server is all the setup there is. An agent without the MCP server reads the same guides as Markdown through the llms.txt at the root of this site.

How an Agent Uses the Tools

The built-in instructions guide the agent through the intended workflow, so you normally just ask for what you want, for example "add a second sensor to the ECU configuration". A typical agent session looks like this:

listDefinitions to find the definition names in scope.
cfgScaffold for the definition it is about to configure, or defExport when editing an existing file.
Edit the .cfg.json5 file with the normal file editing tools.
format on the edited lines, so the edited region matches the workspace conventions without touching the rest.
listEntityPaths before filling a ref value, so the target path is looked up rather than guessed.
cfgValidate and fix the reported diagnostics until the result is valid.
cfgModelMerged or listWorkspaceFiles to confirm the file was discovered and produces the expected merged result.

The last step matters: a valid result is meaningless when the file was never discovered, for example because a .confu setting excludes it. The shipped instructions tell the agent to cross-check discovery, and workspaceOverview explains why a file is out of scope. The same trap is described from the human side in Pitfalls.

Verifying the Setup

Restart the AI tool (or reload its MCP servers) after installing.
Check that the tool lists a Confugami MCP server with the tools above. In Claude Code, run /mcp. In VS Code, open the chat’s tools picker.
Ask the agent to list the available Confµgami definitions. It should call listDefinitions and answer with the definitions of your workspace.

If the server does not start, verify that cfu is on the PATH of the AI tool and run cfu mcp --stdio in a terminal. It must start without an error (stop it with Ctrl+C).

Additional Resources

The cfu CLI reference, for the full cfu mcp command documentation
Workspace & Projects, for the workspace and discovery concepts the tools report about