MPFB MCP

Official

Overview Schema Source Related Servers Discussions Admin

mpfb_set_skin

Destructive

Apply a skin to a MakeHuman character in Blender from MPFB's skin library, replacing all existing materials. Choose a skin by path or fragment or pick a skin type.

Instructions

Give a MakeHuman character a skin, the way MPFB's own skin library panel does.

This destroys every material already on the character. MPFB deletes all materials on the basemesh and on the body proxy, node groups included, before building the new one, and there is no undo across the socket. materials_destroyed names what went, per object.

Name the skin with either path or fragment, never both; mpfb_list_assets reports both for every entry whose object_type is Material (the skins subdir). A fragment is resolved by basename, so resolved_path always reports which file was actually loaded. Give neither only with skin_type="LAYERED", the one type that builds a material from nothing.

skin_type is MAKESKIN (default), GAMEENGINE, ENHANCED, ENHANCED_SSS or LAYERED: five entirely different node trees built from the same MHMAT - MakeSkin's own, a plain PBR material for export, the enhanced one without and with subsurface scattering, and the multilayered one, which MPFB warns is expensive to render rather than to build. All five cost about the same to build, so pick on the look you want. The default follows MPFB's settings panel, not set_character_skin()'s own signature, which defaults to ENHANCED_SSS.

material_instances (default true) asks for the per-vertex-group material slots - fingernails, lips, ears, nipples, toenails, genitals. MPFB's UI forces it off for LAYERED, GAMEENGINE and MAKESKIN, and so does this tool, so the default call creates no instances at all. material_instances_requested comes back beside material_instances_used, with a sentence when they differ.

On applied: true, result carries basemesh_name and bodyproxy_name - MPFB applies the skin to the body proxy too, and nothing else would tell you - plus resolved_path, material_source (the fragment MPFB recorded, written only when an MHMAT was given, so a LAYERED skin with no file leaves the previous value in place, which material_source_before makes visible), skin_type_used, material_instances_requested/_used, materials_destroyed, material_slots per object, material_identified_as, active_body_slot, and two facts nothing in Blender would show you: settings_file_created, true when the enhanced skin types copied enhanced_settings.default.json into your user config directory - the only file mpfb-mcp ever writes outside the .blend - and scale_assumption (METER/DECIMETER/CENTIMETER), which the enhanced types derive from the character's scale_factor and which changes the subsurface radii. It is null for the three types that do not use it, and METER for an ordinary MPFB character.

Refusals come back as applied: false (and so performed: false) with a blocked_by and a sentence, and change nothing on the way to finding out: subject_not_found, unknown_skin_type (with known_skin_types), no_material_given, skin_not_found, not_object_mode, and skin_failed for a failure inside MPFB itself - reported rather than raised precisely because the materials are already gone by then.

Input Schema

TableJSON Schema

Name	Required	Default
`name`	No
`path`	No
`fragment`	No
`skin_type`	No	MAKESKIN
`material_instances`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 3, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Far exceeds the annotations, which only flag destructiveHint/idempotentHint=false. The description spells out exactly what is destroyed (all materials on basemesh and body proxy, node groups included), that there is no undo across the socket, that material_instances is force-disabled for LAYERED/GAMEENGINE/MAKESKIN, and enumerates every refusal path and its blocked_by value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single most important fact - that all materials are destroyed with no undo - is bolded and front-loaded, and each subsequent paragraph covers a distinct concern (input selection, skin_type, instances, outputs, refusals). It is dense and long, but nearly every sentence adds actionable detail rather than padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, multi-mode tool it covers the full contract: inputs, the five material trees, instance-inclusion rules, output fields (including scale_assumption and settings_file_created), and every refusal case. Even though an output schema exists, the description supplies the interpretation an agent needs to act on the results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage and 5 params, the description carries the full burden and delivers: mutual exclusivity of path/fragment, basename resolution semantics, the five skin_type values and what each builds, the counter-intuitive MAKESKIN default, and material_instances' forced-off behavior. Only the 'name' parameter is left largely implicit, but the surrounding context makes its role clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Give a MakeHuman character a skin') and immediately anchors it to MPFB's own skin library panel behavior. The dual target (basemesh plus body proxy) is made explicit, so an agent can distinguish it from set_material_settings or set_asset_material without reading further.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Extensive when-to-use guidance for parameters: path vs fragment vs neither, and which condition selects each skin_type. It points to mpfb_list_assets to obtain fragments. However, it never explicitly distinguishes this tool from sibling tools like mpfb_set_asset_material or mpfb_set_material_settings, so the tool-selection case is inferred rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.