MCP and Agents

MCP and agents

The local MCP server exposes the same operations and JSON results as the CLI. Start it with an absolute config path:

pxtk mcp --config <absolute-config-file>

Only MCP messages go to stdout; process diagnostics go to stderr. Calls resolve configuration again and are serialized. Indexed calls use a fresh LSP session with a reusable cache. Cancellation or closed stdin stops tool-owned child processes, but leaves a game that has already started open.

Register one connection

From a configured mod folder, choose the client registration supported by its installed help:

$configPath = (Resolve-Path .px-toolkit/pxtk.json).Path
codex mcp add paradox-toolkit -- pxtk mcp --config "$configPath"
# Or register with Claude Code, local to this project:
claude mcp add --transport stdio --scope local paradox-toolkit -- pxtk mcp --config "$configPath"

For a local Claude plugin session, use claude --plugin-dir <absolute-path-to-plugins/paradox-toolkit>. The plugin includes MCP registration, so avoid a duplicate connection. For Codex, copy plugins/paradox-toolkit/skills/paradox-toolkit into the project's .agents/skills/paradox-toolkit and register MCP separately.

Check actual tool discovery and call pxtk_status. Registration syntax does not prove that the client can reach the server or approve a writer preview.

Tool inventory

Version 0.2.1 exposes 21 tools. The core tools are pxtk_status, pxtk_search, pxtk_inspect, pxtk_read, pxtk_impact, pxtk_validate, pxtk_new, pxtk_init, pxtk_create, pxtk_loc, pxtk_logs, pxtk_format, pxtk_image, pxtk_playsets and pxtk_launch.

The six tools added in 0.2.0 are pxtk_conflicts, pxtk_rename, pxtk_edit, pxtk_import, pxtk_package and pxtk_migrate. Translation synchronization is an additional action on pxtk_loc, not a separate tool.

Tool discovery supplies input descriptions and output schemas. Inputs reject unknown fields before execution. For example, the token field is expect, not exepct. Results include the envelope as JSON text and structuredContent. Execution errors and incomplete results set isError; new validation findings remain normal results for inspection. Invalid arguments can receive the SDK's standard tool-error response before an operation envelope exists.

Preview and apply

Call pxtk_create with:

{ "kind": "event", "name": "mymod.1", "prefix": "mymod" }

Inspect data.files, then repeat the same request with the returned token:

{
  "kind": "event",
  "name": "mymod.1",
  "prefix": "mymod",
  "write": true,
  "expect": "<data.previewToken>"
}

Replace the placeholder with the actual token. A stale result requires a new preview and review. new requires the token to apply. Rename, edit, import, package and localization sync also require it. Launch uses start: true and expect instead of write.

For baselines, call pxtk_validate with {"writeBaseline":".px-toolkit/before-change.json"}, then after saved edits with {"baseline":".px-toolkit/before-change.json"}. Do not add write; validation does not accept it. writeBaseline authorizes exclusive creation directly.

Client permissions and trusted code

Write-capable tools retain write annotations during previews. Some noninteractive clients therefore need permission for the specific tool before a preview can run. A successful read call does not verify writer access. Use client controls without weakening the server annotations.

Launch declares external access because it can start a game. Migration review also declares write and external-access capability because a trusted local recipe executes with host filesystem and network permissions. Its worker is not a sandbox. Trust only an artifact reviewed by the user, using its exact SHA-256. See Migrations.

Agent workflow

Use either CLI or MCP for an operation, rather than repeating it through both. Start with status when configuration changes. Search narrowly, inspect exact names and read source pages before changing game code. Check impact before changing shared definitions. Keep identifiers and rules tied to returned sources.

Save intended files, preview writes, review all destinations, apply authorized changes and validate. Report incomplete checks, warnings, dynamic-reference limits and truncation. A clean static report or a running process is not evidence that the requested gameplay occurred.