Full, lite, minimal, cli: designing MCP tool modes

Deep dives · ~8 min read · 19 April 2026

godot-catalyst mcp meta

by Fireal Software · ~8 min read

Different MCP clients have different appetites for tools. Claude Code with its 200K context can hold a 240-tool server without sweating. Copilot Chat starts warning at 30 tools and falls over at 60. Cursor is in the middle.

If you ship one fixed tool set, you either leave Claude Code with less than it wants or you lock out everyone else. Godot Catalyst ships four modes instead.

The four modes

Set GODOT_TOOL_MODE in the MCP server env. The value is read once at startup by src/config.ts.

export type ToolMode = "full" | "lite" | "minimal" | "cli";

Each mode registers a different subset:

• full — all ~240 tools. Default. Claude Code, Cursor with sufficient context.
• lite — ~80 tools. Core editor + LSP. Cursor in tight contexts, Windsurf.
• minimal — ~30 tools. Scene/node/script CRUD. Copilot Chat, constrained setups.
• cli — ~14 tools. Offline-only, no Godot required. CI pipelines, analysis scripts.

How the gating works

src/tools/registry.ts has a single TOOL_MODE_MAP keyed by tool name to minimum mode:

const TOOL_MODE_MAP: Record<string, ToolMode> = {
  godot_create_node: "minimal",
  godot_create_resource: "lite",
  godot_parse_tscn: "cli",
  // Everything else defaults to "full"
};

And a shouldRegisterTool function that checks the current mode against the tool’s:

const MODE_RANK: Record<ToolMode, number> = {
  minimal: 0, lite: 1, full: 2, cli: -1,
};

export function shouldRegisterTool(toolName: string): boolean {
  const currentMode = CONFIG.TOOL_MODE;
  const toolMode = TOOL_MODE_MAP[toolName] || "full";
  if (toolMode === "cli") return true;          // CLI tools available in all modes
  if (currentMode === "cli") return false;      // CLI mode — only CLI tools
  return MODE_RANK[toolMode] <= MODE_RANK[currentMode];
}

Each tool file calls this at registration time. If the tool shouldn’t be in the current mode, it never gets registered. The MCP client never sees it. No runtime filtering overhead.

The minimal set

30 tools, picked to cover “scene + node + script” workflows completely:

• Foundation (2): godot_get_status, godot_ping
• Scenes (10): create, open, save, save_as, close, get_tree, get_current, set_current, list_open, reload
• Nodes (10): create, delete, rename, move, reparent, instance, get_properties, set_properties, get_tree, search, get_children
• Scripts (10): create, read, update, delete, attach, detach, open, search_in, get_errors, execute_snippet

Plus godot_reload_handlers (you always want hot reload) and the cli tools (they’re free in every mode).

This is the smallest set where “add a platformer player with movement logic” is possible end-to-end. Drop any of these and the task becomes awkward.

What lite adds

lite adds ~50 more tools over minimal. Highlights:

• Resource CRUD (create_resource, read_resource, update_resource, list_resources, import_asset, get_dependencies, manage_autoloads, uid_to_path)
• Editor state (get_editor_state, select_nodes, get_selected_nodes, undo, redo, screenshot_viewport, screenshot_game)
• Editor settings (get_editor_settings, set_editor_settings)
• Project settings (get_project_info, get_project_settings, set_project_settings, get_project_statistics)
• Filesystem (get_filesystem_tree, search_files)
• Input actions (get_input_actions, set_input_action, delete_input_action)
• Signals (list_signals, connect_signal, disconnect_signal, emit_signal, get_connections, has_connection)
• Build (play_scene, play_main, stop_scene, is_playing, export_project, list_export_presets)
• LSP (all 10 language server tools)

The idea: lite gives you everything you need for “normal Godot development”, but drops the specialist categories (2D/3D manipulation helpers, animation, audio, physics setup, shaders, themes, particles, tilemap cell ops, debug adapter, batch, input simulation, profiling, runtime eval, asset search, spatial, convention, analysis, networking, localization, visual testing, visualization, testing).

Everything dropped has a workaround via lower-level tools. You can still set up collision shapes in lite mode — just call godot_create_node and godot_set_node_properties by hand instead of the godot_setup_collision2d helper.

What full adds

full turns everything on. The extras are:

• Specialized helpers that wrap multiple operations (e.g. godot_setup_physics_body creates the RigidBody, adds a CollisionShape, sets the shape, returns the hierarchy)
• Entire specialist domains: animation, audio, physics, shaders, themes, particles, navigation, tilemap, networking, localization
• DAP debugging (all 10 tools)
• Batch operations (critical for N>3 mutations)
• Input simulation and profiling (useful for agent-driven playtesting)
• AI asset generation (Meshy, Tripo)
• Static analysis (convention enforcement, dead code, dependency graph)
• CC0 asset search (Poly Haven, AmbientCG, Kenney)

The full mode is the “I want Claude to be able to do anything in Godot” set. For Claude Code it’s free — the context overhead is negligible relative to the window. For smaller clients it’s overkill.

The cli mode is weird

cli isn’t a subset of the other modes. It’s a sideways track. Tools tagged cli are available in every mode (they’re the offline file parsers, docs tools, template generators — things that work without Godot running). But in cli mode only these tools are registered.

if (toolMode === "cli") return true;  // Always register CLI tools
if (currentMode === "cli") return false;  // In CLI mode, nothing else registers

The 14 CLI tools:

• godot_parse_tscn / godot_generate_tscn
• godot_parse_tres / godot_generate_tres
• godot_read_project_godot / godot_modify_project_godot
• godot_read_file / godot_list_project_files
• godot_create_gdscript (GDScript template generator)
• godot_validate_tscn
• godot_docs_search / godot_docs_get_class / godot_docs_get_method / godot_docs_list_classes

Use cases for cli:

• CI script that checks all .tscn files parse correctly
• Analysis tool that runs across multiple Godot projects
• Claude session where you don’t want to open the editor
• Writing GDScript templates outside a live project

No WebSocket connection is attempted in cli mode. No Godot installation required. This makes cli the fastest-starting mode by far (~200ms vs ~1-2s for other modes that try to reach port 6505).

Which mode to pick

If your client is Claude Code or Cursor with Tool Search support: full. You’re not gaining anything by limiting.

If your client is Cursor without Tool Search or Windsurf: lite. 80 tools is a sweet spot.

If your client is Copilot Chat, Cline on older models, or you’re on a tight context budget: minimal. 30 tools covers the 80% case.

If you’re running offline analysis, CI, or Claude sessions that don’t need the editor: cli.

You can override per-session. If Claude Code starts getting confused with 240 tools (rare but happens on complex tasks with lots of context already loaded), drop to lite temporarily:

GODOT_TOOL_MODE=lite npx godot-catalyst

The design constraint

The mode boundaries were picked to honor one rule: each mode should be complete for its target workflow. minimal should let you build any game. lite should be comfortable for day-to-day editor work. full should expose everything. cli should cover offline analysis.

If Claude hits “I can’t do X in minimal mode” on a common task, that’s a sign the minimal set is wrong, not that the user should switch modes. Mode switching is heavyweight (it restarts the server and reinitializes the MCP connection) and should be rare.