Runtime Behavior of MCP Skills
This chapter explains how MCP Skills build plans, how optional MCP execution is triggered, and how script-based planning differs from LLM-based planning.
LLM Planning Path
When no script section is present, the subsystem builds a bounded selection prompt from the skill name, the descriptor instructions, the current user request, the available tools, and the current plan limit. It then asks the LLM for a JSON response with a plan array. Each step must identify one allowed tool and supply an argument string plus an optional short reason. The subsystem rejects plans that reference tools outside the allowlist and truncates the plan to the configured limit, which is currently three steps by default.
The planning result is returned as a structured object containing the prompt text, the planning instructions, the selected plan, optional notes, and the filtered list of available tools. In this mode, the MCP Skill behaves as a bounded tool planner whose output can later be executed or inspected without immediately contacting the MCP server.
Script Planning Path
When a script section exists, the subsystem does not call the LLM for planning. Instead, it runs the declared script through the Plan SOPlang interpreter. In that path, the interpreter receives a command registry that exposes the filtered MCP tools together with two built-in commands: prompt, which returns the original prompt text, and workspaceroot, which returns the workspace root directory. Each MCP-tool command schedules a plan step rather than executing the tool immediately.
The resulting plan is returned together with the original script and the filtered tool list. This makes the script path useful when the planning structure should remain explicit and inspectable in the descriptor rather than synthesized by the LLM.
Optional MCP Execution
Actual tool execution is separate from planning. In the current implementation, the subsystem sets execution mode only when agentClientBaseUrl is present in the options. If that value exists, the subsystem creates an MCP client when necessary, lists server tools if the caller did not already provide them, filters those tools through the allowlist, and then executes each planned step through callTool. Each execution result records the step, its parsed arguments, the tool response, and any failure status.
This detail matters because the current code does not treat the mere presence of an agentClient object as sufficient to trigger execution. The execution flag is derived from agentClientBaseUrl. A caller who passes only a client instance without that base URL will still obtain a plan-only result. That is the behavior of the current implementation and should be documented as such.
An MCP Skill can always return a plan. It executes that plan against the MCP server only when the current runtime options enable execution through agentClientBaseUrl.