Projectional Agent Toolkit

The Projectional Agent Toolkit makes MPS projects accessible to AI coding agents. It bundles an MCP (Model Context Protocol) server with a curated catalog of MPS-specific skills, so that agents such as Claude Code, JetBrains AI Assistant, and other MCP-aware tools can navigate, understand, and modify MPS languages and models in a structurally safe way — without resorting to brittle text edits of .mps XML files.

What the toolkit offers

When the toolkit is enabled and connected to an agent, the agent gains:

Projectional MCP tools that operate on the live MPS repository — modules, models, root nodes, the full SNode tree, language structure, editor declarations, typesystem and dataflow engines, generation plans and traces, migrations, the MPS Console, run configurations, and project-wide search. The agent reads and writes the model through these tools instead of editing serialized XML.
JSON node blueprints for creating and updating nodes by concept, properties, children, and references — including bulk root insertion, staged construction for large trees, and passing large blueprints via temporary files.
Bundled Python scripts, installed with the skills, that keep large JSON out of the chat. The agent runs them; you do not have to. blueprint.py builds deep JSON blueprints (such as BaseLanguage bodies or ASTs deeper than ~5 levels) from nested node(...) calls without hand-counting closing brackets. table_to_bulk_insert.py turns a CSV, or rows of JSON (including an optional aggregate root), into a bulk-insert blueprint and can check the inserted model against that table. mps_dump.py and concept_shape.py reduce large structure, node, or concept-details tool results to the few lines needed next. new_project_migration_xml.py generates the version-specific .mps/migration.xml file when creating a new empty MPS project headlessly.
Validation tools for checking nodes, root nodes, entire models, and whole modules (including a language's generators) against the same problem detector that MPS uses interactively (errors, warnings, and information messages). A typesystem, constraints, or scope problem can name the rule that reported it, and auto-applicable quick-fixes can be applied in one pass.
Typesystem queries, since MPS 2026.1.2, so an agent can ask the live type checker what type a node has, what type its context expects, whether one type fits another, what an operator returns, and why a type error happened. See Typesystem.
Dataflow queries so an agent can ask the live dataflow engine what program a node's compiled builders emit, which builder rule emitted an instruction, why code is reported as unreachable or a variable as uninitialized, which assignments reach a read, and which reads a write feeds. See Dataflow.
Generation inspection and debugging so an agent can inspect a model's generation plan, attach or clear custom generation plans on DevKits and Solutions, keep and read transient models from a build, and walk the generation trace forward or backward to find the exact mapping rule, template, or macro that produced a node. See Generation.
Headless migrations so an agent can check and apply pending language and project migrations without opening the modal Migration Assistant wizard, and synchronize a language's version from its migration scripts. See Migrations.
Build and run integration that lets the agent regenerate models, rebuild modules, and launch a main class, one or more test roots (including GeneratorTest roots), or the tests in a model through standard MPS run configurations.
IDE log inspection and diagnostics that allow an agent to read and filter idea.log (by time, level, or regex) through mps_mcp_read_ide_log. This enables verifying write operations, inspecting swallowed errors, and diagnosing unexpected behavior even in standalone MPS instances where project file-read tools cannot access the log directory. See IDE log.
A bundled MPS skill catalog — installed on demand into your project — that teaches an agent how to use the toolkit correctly. Skills cover everything from concept structure and node editing to specific aspects such as editor, constraints, typesystem, behavior, generator, generation plans, migrations, intentions, actions, dataflow, and TextGen, as well as language analysis, modularity, BaseLanguage usage, collections and closures, console queries, tests, and the MPS Build Language. See the Bundled skills section below for the full list.

The result is an agent that can answer non-trivial questions about your languages, including what type a node has and why, inspect dataflow graphs and generation traces, locate problems across models and modules, scaffold new concepts and editors, write and debug generator templates, run migrations, and apply bulk refactorings — while staying inside the model's structure and respecting constraints, references, and used languages.

Before you start

To use the Projectional Agent Toolkit, you need:

JetBrains MPS 2026.1 or later, with the bundled Projectional Agent Toolkit plugin enabled (it's enabled by default).
An MCP-aware AI coding agent, for example Claude Code, JetBrains Junie, OpenAI Codex, or any other tool that can connect to an MCP server.
An open MPS project. The toolkit operates on whichever project is open in the running MPS instance.

How to configure

The toolkit runs as a built-in MCP server inside the MPS process. You connect your agent to it the same way you would connect to any other JetBrains MCP server.

Start MPS and open your project. The MCP server starts automatically and exposes the projectional tools.
The MCP server needs to be enabled in Settings | Tools | MCP Server. Copy the port number shown there — the example below is only a starting point. The default is 64342, the same as IntelliJ IDEA. If that port is already taken (another JetBrains IDE, or a second MPS instance), MPS moves to the next free port and remembers it.
In Settings | Tools | MCP Server | Exposed Tools, enable or disable the individual MCP tools that you want to expose to agents. Consider disabling some of the platform tools (without the mps_mcp_… prefix), because they aren't relevant to MPS projects and can confuse agents.
Configure your agent to talk to the MPS MCP server. The configuration steps — URL, port, and the JSON snippet to add to your agent — are described in the JetBrains help page for the IDE MCP server. See Configure the JetBrains MCP server; the same procedure applies to MPS.
Agent MCP connections are configured in JSON and stored in an agent-specific configuration file, either as part of the project or in the user home folder. Either way, the entry for the MPS MCP server should look something like this (the port number needs to match the MCP server port):
{ "mcpServers": { "mps-mcp-server": { "url": "http://localhost:64342/stream" } } }
From the agent, confirm the connection by asking it to list its available tools. You should see tools prefixed with mps_mcp_… (for example, mps_mcp_get_project_structure, mps_mcp_print_node, mps_mcp_query_types, mps_mcp_query_dataflow, mps_mcp_generation, mps_mcp_run_migrations, mps_mcp_check_root_node_problems, mps_mcp_read_ide_log, mps_mcp_initialize_project_for_agents).

If you don't see the mps_mcp_… tools, recheck the agent's MCP configuration and make sure the MPS instance is running with the Projectional Agent Toolkit plugin enabled.

Initialize your project for agent use

Before doing real work, install the bundled MPS skill catalog. This is a one-time step per checkout. The tool copies the skills into both .agents/skills/ and .claude/skills/ under the repository root (the VCS root, which may sit above the MPS project directory), and writes AGENTS.md and CLAUDE.md there when those files do not already exist. Since MPS 2026.2 it also writes MPS_MCP_SKILL_VERSION.txt into both skill catalogs. That stamp records the MPS version and build the skills came from, so an agent can see when they are stale after an upgrade.

The recommended way is to ask the agent to do it. The toolkit exposes a dedicated tool, mps_mcp_initialize_project_for_agents, that performs the copy and returns the recommended AGENTS.md content.

A short prompt is usually enough:

Please initialize this MPS project for AI agent use by running mps_mcp_initialize_project_for_agents as described in
its tool description (install the bundled skills and create AGENTS.md/CLAUDE.md at the derived VCS root).
If multiple MPS projects are open, call mps_mcp_list_open_projects first and pass the intended project's
agentConfigRoot as targetDirectory. Stop and report any collision.
        

What happens next:

The agent calls mps_mcp_initialize_project_for_agents against your open project.
The tool checks both .agents/skills/ and .claude/skills/. If any folder there has the same name as a skill that would be installed, the tool aborts without touching disk and reports the collisions. Resolve them (rename or delete the conflicting folders) and re-run. Leave project-local skills whose names do not start with mps- — for example *-dsl skills — in place.
On success, the tool copies every bundled skill into both skill catalogs and returns the recommended guide text.
If AGENTS.md or CLAUDE.md did not exist, the tool creates it from that text. Existing guide files are left untouched; the agent should merge the returned text in, keeping project-specific sections.
When the MPS project directory is a subfolder of the VCS root, start the agent at the VCS root and install the skills there. The agent finds the open MPS project through MCP.
Several MPS projects under one VCS root are handled the same way. Keep the project you want open in MPS. If more than one is open and the prompt does not make the target obvious, the agent should ask you which one to use.

The repository root after a successful agent initialization will look like this:

The content of a root of an initialized MPS project

From this point on, any agent opened against the project will discover the skills automatically and follow the entry-point file.

Refreshing the agent's configuration and skills

Each MPS release may include new or updated skills and configuration. After upgrading MPS, refresh the project's agent files to pick up the latest versions. Since 2026.2, a successful install writes MPS_MCP_SKILL_VERSION.txt into both .agents/skills/ and .claude/skills/. The file records the MPS version, build, and whether that build is an EAP. Agents are instructed to compare its build with mpsBuild from mps_mcp_list_open_projects — not to run the installer just to learn the version. When the builds differ, the agent should tell you and ask before refreshing. It should not refresh on its own. A missing stamp only means the skills were installed by an older MPS; absence is not proof that they are stale. You can also ask for a refresh yourself. A short prompt is enough:

Please refresh the MPS agent configuration after the MPS upgrade by running mps_mcp_initialize_project_for_agents and
following the refresh contract in its tool description (delete the bundled mps-* skill folders from
both .agents/skills and .claude/skills so they reinstall, keep project-local skills, merge the returned
agentsFileText into the existing AGENTS.md/CLAUDE.md). If more than one MPS project is open, call
mps_mcp_list_open_projects first and pass the intended project's agentConfigRoot as targetDirectory.
Report any collisions or errors before proceeding.
            

Agents working with outdated skills may make more mistakes and require more corrections, so refresh after every MPS upgrade.

Additional configuration tips

The Terminal tool window in MPS supports running CLI coding agents, so you can interact with the agent directly inside MPS.
For Claude Code specifically, verify that ENABLE_TOOL_SEARCH is set to true (it is the default, but some environments may have overridden it):
"env": { "ENABLE_TOOL_SEARCH": "true" },
This reduces the number of context tokens consumed by the numerous MPS tools.
When agents use MCP or the CLI to shut down MPS, close a project, or open a project, modal dialogs block the IDE's Event Dispatch Thread (EDT) and cause agent commands to hang indefinitely. To prevent MPS from displaying modal confirmation dialogs, adjust the following settings in Settings | Appearance & Behavior | System Settings:
- Confirm before exiting the IDE: clear this checkbox so that MPS shuts down without prompting for confirmation.
- When closing a tool window with a running process: select the Terminate process option (the default is Ask) so that closing a project or exiting MPS doesn't prompt for confirmation when background processes or terminal sessions are active.
- Reopen projects on startup: keep this checkbox selected so that MPS automatically reopens previous projects on startup instead of stopping at the Welcome screen.
- Open project in: select the New window option (or Current window, but don't select Ask) so that opening a project while another is open doesn't display a modal dialog asking which window to use.

Practical ideas on what agents can do with MCP-enabled MPS

When working with agents on MPS code, knowing these tips may come in handy:

Agents can see the root node open in the active editor, the node currently inspected in the Inspector tool window, or the command in the MPS Console input editor — along with the active caret cell, the property, reference, or child role it edits, and the current selection.
Agents can open nodes in the editor, just ask them.
Agents can see the problems (warnings and errors) reported by the model checker on a node, a root, a full model, or an entire module (including a language's generators), see which typesystem, constraints, or scope rule reported an error, and apply auto-applicable quick-fixes in one pass.
Agents can ask the typesystem what type a node has, what type its context expects, whether one type fits another, what an operator returns, and why a node received its type.
Agents can query the compiled dataflow engine with mps_mcp_query_dataflow to inspect the dataflow program emitted for a node, see which builder rule emitted an instruction, diagnose unreachable code or uninitialized variable reads, and trace reaching writes and reaching reads.
Agents can inspect a model's generation plan, attach or clear custom generation plans on DevKits and Solutions, keep and inspect transient models from a build, and walk the generation trace forward or backward with mps_mcp_generation to pinpoint which mapping rule, template, or macro produced a node.
Agents can check and apply pending language and project migrations headlessly with mps_mcp_run_migrations (without the modal Migration Assistant dialog), and synchronize a language's version from its migration scripts with mps_mcp_update_module (SYNC_VERSION).
Agents can inspect the IDE log with mps_mcp_read_ide_log to diagnose internal errors, check why an operation had no visible effect, or verify write operations by inspecting recent warnings and errors in the call window (ignoring records from previous IDE sessions).
Agents can explain MPS code to you.
Agents can explain MPS principles to you if you're not familiar with them.
Agents can insert JSON blueprints or parsed Java code into the MPS Console, add model imports and used languages to the console model, edit the current console command in place, execute console commands, browse history and responses, recall past commands, and clear the console.
Agents can create run configurations for a main class, several test roots (including GeneratorTest roots), or a whole test model, and execute them.
Agents can see and trigger intentions as well as quick-fixes associated with nodes.
Agents can clone existing nodes (COPY_NODE), reorder children (MOVE_CHILD), and move subtrees to a new parent or promote them to root nodes (MOVE_NODE_TO_PARENT) — including across models with automatic reference and import repair.
Agents can start/stop MPS, open/close MPS projects, and create new empty MPS projects headlessly (using new_project_migration_xml.py to generate the version-matching .mps/migration.xml).
Multiple agents can work on a single project at the same time.
Once a language structure is set, you can have multiple agents working on different aspects of language definition concurrently.
Subagents may be conveniently utilized for parallel work on independent tasks of the same MPS model or language.
Make sure you initialize your project for agent use — without the skills installed and the AGENTS.md/CLAUDE.md entry point, agent performance will degrade significantly.
For a large import, ask the agent to use the bundled table_to_bulk_insert.py script, and for deeply nested AST blueprints (such as BaseLanguage bodies), ask it to use blueprint.py instead of pasting huge or deeply nested JSON blueprints into the chat.
If you see an agent reading or writing MPS model files directly, stop it and redirect it to use the MPS MCP tools.
Prefer working in smaller steps to keep the context size manageable for the agent. Instead of having an agent design a complete language, ask it to do a single aspect at a time, or split the big task into multiple pieces of cross-aspect functionality.
/rewind in Claude Code can save you tokens when you let the agent forget the latest part of your conversation. For example, for a conversation like:
- You: "Define structure"
- Agent: "Structure created"
- You: "Create editor"
- Agent: "Editor created"
You can use /rewind to roll back the conversation and have the agent forget the editor creation part while keeping the code on disk. This frees up context before you ask the agent to create the generator or the constraints aspect. The structure part of the conversation is still needed, so keep it in context.
If you want to use a less powerful model:
- Split the goal into smaller tasks with clear boundaries, and free unnecessary context after each task if possible.
- Provide more guidance and be specific. For example, say Create a constraints root for concept X, define the 'can be child' function to enforce … instead of Enforce … on X.
- Explicitly load required skills, such as /mps-mcp-workflow, /mps-model-manipulation, /mps-collections-and-closures, /mps-baselanguage, and /mps-node-editing, do not leave the skill selection process to the agent's randomness. Most model-code bodies need both mps-model-manipulation (smodel) and mps-collections-and-closures (sequences, foreach, and closure literals).

Recommended agent configurations

Not every agent and model combination is a good fit for every kind of MPS work. In general, the most powerful models are best suited for defining the generator, constraints, and typesystem aspects, and for all code that mixes BaseLanguage with extensions such as smodel, collections, and closures. Less powerful models can save you money on less demanding aspects — structure or editor definitions. Code or language introspection can also work well with less powerful models. When authoring code in a DSL, the required model capability depends largely on the complexity of the DSL and the task.

Documenting your DSLs with mps-dsl-memory

When you work with MPS languages and DSLs alongside AI agents, you can create project-local documentation that helps agents understand your custom languages and work more effectively with them.

The mps-dsl-memory skill enables you to bootstrap or refresh DSL documentation by systematically capturing:

Concept hierarchies — which concepts are rootable, their properties, child roles, and references
Sandbox examples — representative model instances and their structure
Workflows — recipes for creating and editing common DSL patterns
Gotchas — reference formats, ordering constraints, and validation rules specific to your language
Blueprint templates — reusable JSON skeletons and subtrees for common operations

When to use

Use mps-dsl-memory when:

You have a new MPS language or DSL, and you want AI agents to work with it effectively.
An existing DSL skill is outdated and needs a refresh after language changes.
You want to preserve your knowledge about a DSL in a persistent, reusable form for future sessions.

How it works

The skill analyzes your MPS project to discover language concepts and sandbox examples, then generates a structured documentation package under .agents/skills/<dsl-name>-dsl/. This includes reference files for concepts, sandbox models, common workflows, and known gotchas, designed to be consumed by AI agents in future sessions.

The generated skill stays in your project and requires no external tools or services. You can refine and maintain it alongside your language definitions, updating it as your DSL evolves.

What you get

Once documentation is generated, agents in future sessions will have detailed references for:

Which concepts can be roots and how they should be structured.
What properties and relationships each concept supports.
Where to find working examples in your sandbox models.
Common patterns and potential pitfalls specific to your language.
Ready-to-use JSON templates for creating new models.

This accelerates your work with AI agents because they can leverage this project-specific knowledge automatically, without requiring you to re-explain your DSL structure each time.

Working with the toolkit: prompting tips

The bundled skills are written so that an agent can follow them. To get the most out of them, your prompts should encourage the agent to load the relevant skill, use the MCP tools, and validate its work. This matters most for less capable LLMs — top-of-the-line models typically apply these tips on their own, guided by the instructions in AGENTS.md/CLAUDE.md.

Point the agent at the right skill

Skills are organized by topic. Naming the area you're working on helps the agent load the right SKILL.md instead of guessing. For example:

"I'm changing the editor for ClassConcept. Load mps-aspect-editor-menus-and-keymaps and the editor technical reference first."
"This is a generator template issue — start with the mps-aspect-generator skill."
"Before editing the typesystem rules, read mps-aspect-typesystem."
"You're writing tests in an MPS test model — read mps-tests."
"This behavior method filters a sequence — load mps-collections-and-closures alongside mps-model-manipulation."

If you aren't sure which skill applies, ask the agent to consult mps-language-aspects-overview or mps-mcp-workflow first; these act as indexes into the rest of the catalog.

Prefer projectional MCP tools over file edits

State explicitly that you want changes made through MCP tools, not through text edits of .mps files. A useful framing:

"Use only the MPS MCP tools to make changes. Do not hand-edit .mps model files."
"Resolve concepts and nodes by persistent reference before editing."
"After every structural change, run mps_mcp_check_root_node_problems on the affected root."

Work in small, validated steps

Agents work best when they validate as they go. Ask for an explicit loop:

Explore the project with mps_mcp_get_project_structure and mps_mcp_search_root_node_by_name.
Print the relevant nodes with mps_mcp_print_node.
Propose a JSON blueprint or operation.
Apply it with the appropriate tool (mps_mcp_update_node, mps_mcp_insert_root_node_from_json, mps_mcp_update_root_node_from_json, …).
Validate with mps_mcp_check_root_node_problems.
Regenerate or rebuild as needed (mps_mcp_alter_nodes with MAKE).

A prompt template that captures this:

For each change, follow this loop:
Explore the relevant model/concept and read existing nodes.
Describe the change you intend to make and which MCP tool you will use.
Apply the change.
Validate the affected root with mps_mcp_check_root_node_problems.
Stop and summarize before moving to the next change.
Use the bundled MPS skills under .agents/skills/ whenever they apply.
            

Use names, then references

When pointing the agent at something, start with names ("the Calculator root node in model calc.demo ") and let it resolve them to persistent references via the MCP tools. Avoid pasting MPS XML short IDs from .mps files — they are an internal encoding and aren't interchangeable with the persistent references the tools expect.

Keep the agent honest

If the agent claims a change has been made, ask it to:

print the affected node back with mps_mcp_print_node,
show the validation result,
rebuild (or regenerate) if downstream Java or Kotlin code is involved, and
check the IDE log with mps_mcp_read_ide_log (for example, with sinceMinutes=2 and minLevel="WARN") if an operation reported success but the model remains unchanged or behaves unexpectedly.

This catches the common failure mode where an agent describes a change in prose without actually committing it through the tools.

Use /rewind

The /rewind command of Claude Code can save a considerable number of tokens if used wisely. For example, when defining a language, you typically first define the structure and then the editor. Before you move on to, say, the generator, use /rewind to roll the conversation back to the point where structure was complete, discarding the editor details and freeing up context space.

Bundled skills

mps_mcp_initialize_project_for_agents installs the following skill set into both .agents/skills/ and .claude/skills/. Each skill is a self-contained SKILL.md (with optional supporting files) that teaches the agent how to use the toolkit for a specific area. Some skills also include the Python scripts mentioned above.

Workflow and orientation: mps-mcp-workflow, mps-project-management, mps-language-aspects-overview, mps-language-analysis, mps-language-inheritance, mps-language-modularity, mps-dsl-memory.
Structure and nodes: mps-aspect-structure-concepts, mps-node-editing, mps-quotations, mps-model-manipulation.
Language aspects: mps-aspect-accessories, mps-aspect-actions, mps-aspect-behavior, mps-aspect-constraints, mps-aspect-dataflow, mps-aspect-editor, mps-aspect-editor-menus-and-keymaps, mps-aspect-generation-plan, mps-aspect-generator, mps-aspect-intentions, mps-aspect-migrations, mps-aspect-textgen, mps-aspect-typesystem.
BaseLanguage and DSLs: mps-baselanguage, mps-collections-and-closures, mps-console, mps-lang-core-xml.
Tests, build, and tooling: mps-tests, mps-build-language, mps-distribution-build, mps-ide-plugin, mps-run-configurations.

Several skills ship with offline Python helper scripts under their scripts/ subfolder so agents can generate or project large JSON files without filling the context window:

mps-mcp-workflow/scripts/mps_dump.py — projects large structure, node, or concept-details result files down to compact views (roots, models, node, tree, shape, count).
mps-language-analysis/scripts/concept_shape.py — summarizes a mps_mcp_get_concept_details dump as one line per property, reference, and child role.
mps-node-editing/scripts/blueprint.py — constructs deep JSON node blueprints (such as BaseLanguage bodies or ASTs deeper than ~5 levels) from nested Python node(...) calls and writes them to a temporary file.
mps-node-editing/scripts/table_to_bulk_insert.py — converts CSV or JSON rows (plus an optional aggregate root) into a bulk-insert blueprint and verifies the resulting model with --verify.
mps-project-management/scripts/new_project_migration_xml.py — derives the version-specific .mps/migration.xml from an MPS installation when creating a new empty project headlessly.

mps-model-manipulation covers smodel — querying, navigating, creating, and mutating nodes. Collection types, sequence operations, foreach, and closure literals live in the companion skill mps-collections-and-closures. Most method, rule, and query bodies need both.

Skill files are copied into your checkout, so you can inspect, customize, or extend them. Project-local edits aren't overwritten on subsequent runs of mps_mcp_initialize_project_for_agents; the tool refuses to overwrite an existing skill folder in either catalog and instead reports the collision.

MCP tool reference

The following tools are exposed by the Projectional Agent Toolkit MCP server. Tool names are prefixed with mps_mcp_ and are visible to any connected agent. Small results come back directly; results above a size limit are written to a temporary file, and the tool returns that path instead.

Console

Tool	Description
`mps_mcp_insert_console_command_from_json`	Inserts a JSON-blueprint node (a console `Command` or BaseLanguage statements) into the MPS Console input editor as editable code without executing it.
`mps_mcp_get_console_history`	Lists the Console's command history, optionally including command output (`includeResponses=true`) with one-line previews and `previewComplete` flags.
`mps_mcp_recall_console_command`	Copies a past Console command back into the input field without running it.
`mps_mcp_run_console_command`	Runs whatever is currently in the Console input editor against the live project.
`mps_mcp_clear_console`	Clears the MPS Console history (matching the Console toolbar's Clear button), keeping the current input unless `clearInput=true` is passed; supports `dryRun=true`.

In addition to the dedicated Console tools, agents can read the current unexecuted command with mps_mcp_get_current_editor_root_node(source="console"), edit nodes inside the current Console input in place with mps_mcp_update_node and mps_mcp_alter_nodes, insert parsed Java directly into the Console input with mps_mcp_parse_java_and_insert(insert.mode="console"), and add temporary imports or used languages to the Console model via mps_mcp_model_dependency and mps_mcp_model_used_language with modelReference="console".

Editor

Tool	Description
`mps_mcp_scaffold_editor`	Auto-generates a default `ConceptEditorDeclaration` (or `EditorComponentDeclaration` when `type="component"`) for a concept, wiring selected or all properties, children, and references to matching cell models, and automatically building an uncompiled structure model when needed.

Project, modules, and models

Tool	Description
`mps_mcp_list_open_projects`	Lists IDE projects open in this MPS instance, reports the running MPS version and build used to detect stale skills, and reports the IDE log directory and log file location (see IDE log).
`mps_mcp_close_project`	Closes the current MPS project (with optional `force=true` and `shutdownWithLastProject=true`).
`mps_mcp_get_project_structure`	Project discovery, name-based searching, dependency analysis, and AST inspection (with `nodeDetail="names"` and `nodeDepth` projections, plus transient model inspection).
`mps_mcp_reload_all`	Reloads all module classes from disk.
`mps_mcp_create_module`	Creates a new MPS module (`solution`, `language`, `devkit`, or `generator`), with optional companion modules, initial `facets`, and automatic `templates@generator` scaffolding for generators.
`mps_mcp_update_module`	Renames (`RENAME`), moves in the Project View (`CHANGE_VIRTUAL_FOLDER`), or deletes (`DELETE`) an MPS module; derives and synchronizes a language's version from its migration scripts (`SYNC_VERSION`); or attaches/clears a generation plan model on a DevKit or Solution (`SET_GENERATION_PLAN`, `CLEAR_GENERATION_PLAN`).
`mps_mcp_get_module_facets`	Returns the active and persisted facets installed on a module.
`mps_mcp_list_facet_types`	Lists all available MPS module facet types and their applicability.
`mps_mcp_update_module_facet`	Enables, disables, or configures a module facet.
`mps_mcp_module_dependency`	Adds or removes a module dependency with scope control (`Default`, `Design`, `Compile`, `Runtime`, `Provided`, `Generation Target`, `Extends`), including DevKit exports.
`mps_mcp_create_model`	Creates a new empty model in a given module, auto-populating default used languages, devkits, and imports for recognized language aspect models.
`mps_mcp_update_model`	Renames (`RENAME`) or deletes (`DELETE`) an MPS model, or sets its "Do not generate" flag (`SET_DO_NOT_GENERATE`).
`mps_mcp_model_dependency`	Adds or removes model imports (including on `"console"`), and ensures the module has a matching Default dependency.
`mps_mcp_model_used_language`	Adds or removes a used language or devkit from a model (including `"console"`).

Migrations

Agents can inspect and execute pending project and language migrations headlessly without opening the modal Migration Assistant wizard. While an agent is making mps_mcp_* calls, MPS automatically suppresses the modal Migration Assistant popup and displays a notification balloon instead.

Tool	Description
`mps_mcp_run_migrations`	Lists (`CHECK`, default, read-only) or applies (`APPLY`) pending language, refactoring-log, and project migrations, updating module descriptor versions and reporting any blockers or unbuilt/stale language runtimes.

When authoring or editing migration scripts in a language's migration aspect, use mps_mcp_update_module with operation="SYNC_VERSION" to derive the language module's version from its migration scripts, then rebuild the language module with mps_mcp_alter_nodes (MAKE, rebuild=true) before running mps_mcp_run_migrations.

Nodes

Tool	Description
`mps_mcp_create_root_node`	Creates a new root node in the specified model.
`mps_mcp_insert_root_node_from_json`	Bulk-creates one or more root nodes from an inline JSON blueprint or temporary file path with atomic rollback.
`mps_mcp_update_root_node_from_json`	Rewrites or deletes a root node from an inline JSON blueprint or temporary file path.
`mps_mcp_update_node`	Surgical property, reference, and child updates (`ADD`/`SET` × `CHILD`/`PROPERTY`/`REFERENCE`) on any project or Console input node; accepts a temporary file path for large `childJson` blueprints.
`mps_mcp_alter_nodes`	Structural mutations and builds: reorder children (`MOVE_CHILD`), move a node to a new parent or promote it to a root across models (`MOVE_NODE_TO_PARENT`), deep-copy nodes (`COPY_NODE`), make/rebuild with optional `saveTransientModels=true` (`MAKE`), and repair broken references (`FIX_REFERENCES`).
`mps_mcp_print_node`	Prints a node (including nodes in kept transient models) as `JSON`, `HTML`, or `PLAIN TEXT`. Small prints are returned directly; larger ones are saved to a temporary file.
`mps_mcp_query_nodes`	Read-only node queries: find instances (`FIND_INSTANCES`, supporting multi-concept queries and `detail="count"`) and usages (`FIND_USAGES`), get parent, root, model, child role, node index, and siblings, and read a node's type (`GET_TYPE`) or the type its context expects (`GET_EXPECTED_TYPE`).
`mps_mcp_get_current_editor_root_node`	Returns the node currently focused in the active editor (`source="editor"`), the Inspector tool window (`source="inspector"`), or the Console input (`source="console"`), along with the caret cell descriptor (`caret`) and selection state (`selection`).
`mps_mcp_open_node`	Opens a node in the MPS editor (or opens its containing root and focuses the target node).
`mps_mcp_check_root_node_problems`	Validates a node, a root, a full model, or an entire module (including a language's generators). Reports rule provenance (`rules`), skipped subtrees (`uncheckedSubtrees`), per-root/per-model problem summaries (`perRoot=true`), and available quick-fixes (with optional `autoApplyQuickFixes=true`).
`mps_mcp_search_root_node_by_name`	Finds root nodes whose name matches any of the given strings across editable modules, visible dependencies, or explicit models/modules.
`mps_mcp_parse_java_and_insert`	Parses Java source with the MPS `JavaParser` and inserts the result as roots, children, replacements, or the current Console command (including inside `ConceptBehavior` and concept functions), returning any type-system problems on the inserted nodes.

Typesystem

Since MPS 2026.1.2, an agent can question the live typesystem instead of reading rule definitions and guessing. The answers are what the type checker itself decides. A node's own type, and the type its context requires, are operations of mps_mcp_query_nodes (Nodes): GET_TYPE and GET_EXPECTED_TYPE. In Object o = s, for example, s has type String and is expected to be Object. A node with no type answers null.

Tool	Description
`mps_mcp_query_types`	Asks the typesystem whether one type fits another (`IS_SUBTYPE`), what a type widens to (`SUPERTYPES`), what types have in common (`COMMON_SUPERTYPE`), how to view a type as a given concept (`COERCE`), what an operator returns (`OPERATION_TYPE`), and why a node has its type (`EXPLAIN_TYPE`).

EXPLAIN_TYPE is the Type-system Trace for one node, without opening the tool window: the assignments, equations, and subtype checks that produced its type, each citing the rule that added it — including the subtyping or replacement rule that made a type fit. A problem from mps_mcp_check_root_node_problems can name the reporting rule directly, without a trace.

The bundled mps-mcp-workflow and mps-aspect-typesystem skills tell the agent which query to use. Refresh the project's skills after upgrading MPS so the agent picks them up. See Refreshing the agent's configuration and skills.

Dataflow

An agent can query the live dataflow engine instead of reading dataflow builder declarations and simulating the control/data flow graph by hand — the headless equivalent of Language Debug | Show Data Flow Graph.

Tool	Description
`mps_mcp_query_dataflow`	Builds the compiled dataflow program for a node and returns its instructions, emitting builder rules, and `unreachable`, `uninitializedReads`, and `unusedAssignments` sets (`PRINT_PROGRAM`), or traces def-use chains to find which writes reach a read (`REACHING_WRITES`) and which reads a write feeds (`REACHING_READS`).

Generation

An agent can inspect a model's generation plan, examine the transient models kept by a build, and trace nodes forward or backward across generation steps — the headless equivalent of Show Generation Plan, the Project view's Transient models folder, and Show Generation Trace / Traceback.

Tool	Description
`mps_mcp_generation`	Computes the generation plan make would use for a model, including steps, checkpoints, forks, and language coverage (`PLAN`); lists the transient models and checkpoints kept by a build run with `saveTransientModels=true` (`TRANSIENT_MODELS`); traces a node `FORWARD` or `BACKWARD` across generation steps to identify the mapping rules, templates, and macros that produced it (`TRACE`); or frees kept transient models and checkpoints (`DROP_TRANSIENT_MODELS`).

Tool

Description

mps_mcp_generation

Computes the generation plan make would use for a model, including steps, checkpoints, forks, and language coverage (PLAN); lists the transient models and checkpoints kept by a build run with saveTransientModels=true (TRANSIENT_MODELS); traces a node FORWARD or BACKWARD across generation steps to identify the mapping rules, templates, and macros that produced it (TRACE); or frees kept transient models and checkpoints (DROP_TRANSIENT_MODELS).

To debug a misgeneration, run mps_mcp_alter_nodes (MAKE) with saveTransientModels=true on the sample model, inspect the intermediate models via TRANSIENT_MODELS (using mps_mcp_print_node, mps_mcp_query_nodes, or mps_mcp_get_project_structure on their transient references), and call TRACE with direction="BACKWARD" on a transient output node to locate the rule or template that produced it. Custom generation plans can be attached to or cleared from a DevKit or Solution with mps_mcp_update_module (SET_GENERATION_PLAN, CLEAR_GENERATION_PLAN).

Intentions & Quick-fixes

Tool	Description
`mps_mcp_list_node_intentions`	Lists the intentions and quick-fixes available on a node (the headless equivalent of the editor's Alt+Enter menu).
`mps_mcp_apply_intention`	Applies one intention or quick-fix from a listing or a check report, inside an undoable command.

Language structure

Tool	Description
`mps_mcp_alter_structure`	Creates, renames, and deletes concepts, enumerations, properties, children, and references.
`mps_mcp_query_structure`	Read-only structure queries: inheritance, aspects, references, enum literals, and smart-ref status.
`mps_mcp_get_concept_details`	Returns detailed metadata (or structural shape only with `detail="shape"`, plus `featureId` and `sourceNode` refs) for listed concepts or all concepts in a language, reading unbuilt project languages directly from their structure declarations.
`mps_mcp_search_concepts`	Free-text search for concepts and interface concepts (AND-combines multi-word queries).

IDE log

An agent can inspect the IDE's own log (idea.log) directly through mps_mcp_read_ide_log. Many internal failures — such as caught exceptions in node factories, migration scripts, lightweight DSL initializers (AutoInitDSLClass), or behavior methods called from editor or checking code — are swallowed and only logged to idea.log without surfacing in an MCP response envelope. When a tool reports success (ok: true) but the expected effect is missing, the IDE log provides the decisive evidence.

Tool	Description
`mps_mcp_read_ide_log`	Reads the tail of `idea.log` as parsed records, filtered by time (`sinceMinutes`, `since`), log level (`minLevel`), and Java regex (`grep`), flagging records from previous IDE sessions and automatically following rotated log files.

Key capabilities and parameters of mps_mcp_read_ide_log include:

No path required and works for standalone MPS: Unlike standard file-reading MCP tools (which reject paths outside project roots), mps_mcp_read_ide_log reads the IDE log automatically even when MPS is run as a standalone application whose log resides in platform-specific system directories.
Structured records and session boundary detection: Each log record is returned as a structured object containing ts (timestamp), level (INFO, WARN, ERROR, SEVERE, and so on), category, message, and optional stackTrace in chronological file order. Because idea.log is not truncated on IDE startup, records logged before the current IDE process started (ideStartTimestamp) are marked with previousSession: true (counted in previousSessionRecords) so agents can ignore shutdown noise from earlier sessions. Summary metadata is returned in levelCounts, filesRead, totalRecordsScanned, returnedRecords, and truncatedByTail.
Filtering: Constrain the window with sinceMinutes (last N minutes) or since (ISO-8601 or log timestamp), filter by minLevel (case-insensitive: INFO by default, WARN, ERROR/SEVERE, or TRACE/DEBUG), and search record headers and stack traces using a Java regex with grep.
Automatic rotation handling: When idea.log exceeds 10 MB and rolls over into idea.1.log, idea.2.log, and so on, the tool automatically walks into older rotated files to cover the requested time window (up to 5 files or 60 MB).
Result sizing: Results are limited by tailLines (1..5000 records, default 200). If the output exceeds maxInlineBytes (default 20,000 characters), it is saved to a temporary file, with the summary preserved in details.

The top-level logDirectory and logFile paths are also reported by mps_mcp_list_open_projects (Project, modules, and models) for external inspection or tooling.

Miscellaneous

Tool	Description
`mps_mcp_initialize_project_for_agents`	Installs the skill catalogs and guide files, and writes the skill version stamp.
`mps_mcp_create_run_configuration`	Creates or replaces a run configuration for a main class, one or more test roots (including `GeneratorTest` roots), or the tests in one or more models.

Troubleshooting

Agent doesn't see mps_mcp_… tools. Make sure MPS is running with the Projectional Agent Toolkit plugin enabled and the agent is connected to the MPS MCP server. See Configure the JetBrains MCP server.
mps_mcp_initialize_project_for_agents fails with a collision error. A folder under .agents/skills/ or .claude/skills/ already uses the name of a bundled skill. Move or rename it and run the tool again. Do not delete project-local skills whose names do not start with mps-.
Agent edits .mps files directly. Re-prompt with explicit instructions to use only MPS MCP tools, and reference mps-mcp-workflow and the entry-point file (AGENTS.md or CLAUDE.md).
Changes aren't reflected in generated Java or Kotlin. Ask the agent to run mps_mcp_alter_nodes with MAKE on the affected models or modules, and to check for compilation problems afterwards.
A tool call answers success but the change is missing or fails silently. Many errors (such as exceptions in node factories, migration scripts, lightweight DSL initializers, or behavior methods) are caught internally and only logged. Ask the agent to inspect the IDE log with mps_mcp_read_ide_log (using sinceMinutes=2 and minLevel="WARN") to uncover logged warnings or exceptions. The log directory and live file can also be identified via mps_mcp_list_open_projects.
A call to an MCP tool never returns. Check whether MPS has a modal dialog open. A modal dialog blocks the EDT and can prevent the server from acquiring the write lock needed for MCP processing. While an agent is actively making mps_mcp_* calls, MPS automatically suppresses the modal Migration Assistant wizard and shows a notification balloon instead so the agent can run migrations headlessly with mps_mcp_run_migrations; however, the dialog can still appear if it opened before the first MCP call, after an idle timeout, or when a brand-new project is opened without a matching .mps/migration.xml — dismiss it, or have the agent generate that file with new_project_migration_xml.py from the mps-project-management skill before opening the project. Another possibility is that the agent's request was rejected by the client-side implementation of the MCP protocol because it didn't have enough permissions to run a potentially harmful, state-mutating MCP tool. In both cases, asking the agent why the MCP call failed should clarify what happened.

References

Configure the JetBrains MCP server — connecting MCP-aware agents to JetBrains IDEs and MPS.
Model Context Protocol — the open protocol used by the toolkit.
MPS User's Guide — main entry point to MPS documentation.

29 October 2026