Funplay Cocos MCP vs Manual mcp.json: One-Click Config Tradeoffs

Funplay Cocos MCP ships a one-click configuration button that writes client-specific MCP settings for seven AI coding tools, including Trae and Kiro. The manual alternative is a five-line JSON block — simpler to understand but easier to misconfigure when you switch clients.

What Funplay Cocos MCP Is

Funplay Cocos MCP is an editor extension for Cocos Creator 3.8 or later that exposes 67 tools, 4 built-in prompts, and 8 MCP resources through an HTTP endpoint. The server starts on 127.0.0.1 port 8765, with automatic fallback across up to 20 sequential ports if that port is occupied. The primary tool, execute_javascript, replaces most narrow-purpose tools by running arbitrary JavaScript in either the scene or the editor context. It does not modify your built game — it operates entirely within the editor.

The extension launched in version 0.1.0 on 2026-04-15 and received a patch to 0.1.1 the next day with bug fixes and improved tool descriptions. You can find the source at the Funplay Cocos MCP repository.

Why This Matters

Cocos Creator does not ship with a first-party MCP integration. Funplay Cocos MCP fills that gap, giving AI coding agents the ability to inspect scenes, manipulate nodes, and execute editor scripts without leaving the terminal or IDE. Compared to the sibling Funplay Unity MCP (79 tools, requires Unity 2022.3 or later) and the Funplay Godot MCP (105 tools, requires Godot 4.2 or later), the Cocos version has fewer tools but uniquely supports one-click configuration for Trae and Kiro — two clients the Unity and Godot extensions do not configure automatically.

Installation

You have two options:

Project-local extension. Clone or copy funplay-cocos-mcp/ into your project's extensions/ folder. Open Cocos Creator, go to Extension → Extension Manager → Refresh. The extension appears in the list.
Global extension. Place the folder at ~/.CocosCreator/extensions/. This makes it available across every project on that machine.

After installation, an MCP Server panel appears in the Cocos Creator editor. Click Start Server to boot the HTTP endpoint. Once running, your AI client can connect.

One-Click Configuration

The MCP Server panel in Cocos Creator includes a one-click configuration feature. It detects which AI clients you have installed and writes the correct configuration file for each one. Supported clients:

Claude Code
Claude Desktop
Cursor
VS Code (Copilot or MCP extension)
Codex CLI
Trae
Kiro

Click the button, restart your AI client if prompted, and the connection is live. This is the fastest path from zero to a working setup. It handles file paths, port numbers, and config-format quirks across all seven clients.

For more background on MCP integrations and game-development AI workflows, see the articles at gamebooom.ai/en/blog/.

Manual Configuration

If you prefer full control over your config files — or if the one-click button does not cover your client — you can write the settings yourself. The server speaks plain HTTP, so the configuration is minimal.

Claude Code or Claude Desktop — add this to your mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "funplay-cocos": {
      "type": "http",
      "url": "http://127.0.0.1:8765/"
    }
  }
}

Codex CLI — add this to your Codex TOML config:

[mcp_servers.funplay-cocos]
url = "http://127.0.0.1:8765/"

That is the entire manual setup. The URL points to the local server started by the extension. If the default port is busy and the extension fell back to a different port, you must update the URL to match.

One-Click vs Manual: The Tradeoffs

When One-Click Wins

Multi-client workflows. If you use Claude Desktop for planning and Cursor for implementation, one-click writes config for both in a single action. Doing this manually means editing two files in two different locations with two different formats.
Trae and Kiro support. These two clients have unique config requirements. One-click handles them automatically. The Unity MCP and Godot MCP do not offer this, which makes the Cocos extension the only Funplay MCP with built-in Trae and Kiro config generation.
Port fallback awareness. If port 8765 is occupied and the server starts on 8766 or higher, one-click detects the actual port and writes the correct URL. Manual config requires you to check the MCP Server panel and update the URL yourself.
Onboarding speed. For teams new to MCP, one-click removes the "which file do I edit?" question entirely.

When Manual Wins

Reproducible configs in version control. A committed mcp.json is transparent. Every team member gets the same file. One-click writes to local app-data directories that vary per OS and user, which makes it harder to audit or share.
CI or headless environments. Automated pipelines do not have a Cocos Creator GUI panel to click. A static config file you provision via script is the only option.
Custom tool filtering or server options. If your client supports additional fields — timeouts, disabled tools, headers — manual config lets you add those. One-click writes a minimal working block and nothing more.
Pinned setups. If your team standardizes on a single client and a single port, writing one five-line JSON block once is simpler than training everyone to find and click the button.

Practical Recommendation

Use one-click for your own workstation when you are prototyping. Commit a manual mcp.json to your repo when you are ready to share the project with a team. The two approaches coexist fine — one-click for speed, manual for control.

Built-In Prompts and Resources

The extension bundles four prompts: fix_script_errors, create_playable_prototype, scene_validation, and auto_wire_scene. These give your AI client structured entry points for common Cocos Creator tasks without requiring you to write detailed instructions each time.

The eight MCP resources expose editor state — scene hierarchy, component properties, project settings — so your AI agent can query context before acting. Combined with execute_javascript, these resources let an agent read the scene graph, compute a change, and execute it in one pass.

Gotchas and Limitations

Port conflicts are silent. If another process grabs port 8765, the extension falls back to the next available port without a prominent notification. If your AI client cannot connect, check the MCP Server panel for the actual port and update your config.

Editor-only scope. This extension does not touch your built game. It cannot help with runtime issues on a device or in a browser. It is a development-time tool, not a deployment tool.

Cocos Creator version lock. You need Cocos Creator 3.8 or later. Earlier versions are not supported. There is no workaround — the extension uses APIs introduced in 3.8.

JavaScript execution trust model. The execute_javascript tool runs arbitrary code in the editor. Any AI agent connected to the server can call it. If you expose the server beyond localhost — even accidentally — you open a remote-code-execution path. Keep the server bound to 127.0.0.1 and shut it down when you are not using it.

Fewer tools than sibling MCPs. The Cocos extension offers 67 tools compared to Unity's 79 and Godot's 105. If you are evaluating engines and MCP coverage is a factor, be aware that Cocos coverage is narrower. The execute_javascript tool compensates by letting you do almost anything, but you may write more ad-hoc code than with the wider tool surfaces of the Unity or Godot integrations.

No built-in authentication. The HTTP endpoint has no API key or token system. Security depends entirely on network isolation.

When Not to Use It

Do not use this extension if you need to automate Cocos Creator in a CI pipeline — there is no headless server mode documented for the current version. Do not use it if your team is not already working with an MCP-compatible AI client; the extension adds overhead without benefit in a purely manual workflow. Do not use it on a shared machine where multiple users might start conflicting server instances on the same ports.

Getting Started

Install the extension, start the MCP Server panel in Cocos Creator, and use one-click config to connect your preferred AI client. Read more MCP integration guides and game-development AI tutorials at gamebooom.ai/en/blog/.