The Patchworld Model Context Protocol (MCP) server enables AI agents to interact directly with the Patchworld app. This allows agents to perform complex, contextual actions such as spawning entities, connecting blocks, and querying real-time state information.
You can use the MCP server to control any instance of the Patchworld app running on any device, as long as it is logged in with the same user account that generated the API key in the portal.
To allow external connections on your device, open the in-app console in the Patchworld app and run:
agent_control on
To see the full capabilities and available tools, refer to the Tools Reference page.
Fastest setup: copy this page and send it to the AI agent you want to use. Ask the agent to set up Patchworld MCP for its own client, then share your Patchworld API key with that agent when it needs to configure the connection.
You can paste the API key into the chat and it will work. We do this too when we are moving fast. Best practice, especially with coding agents, is to save the key in a temporary local text file or environment variable and give the agent that file path or variable name instead. Call it the slightly less wild-side setup.
Smooth copy-paste prompt:
To connect an AI client to the Patchworld MCP server, you will need a Patchworld API key (Bearer token).
You can easily generate and manage your API keys directly from the Patchworld portal:
Once generated, save your token securely. You will use it in place of <YOUR_BEARER_TOKEN> in the configurations below.
Configure the Patchworld MCP server under the appropriate configuration file for your AI client. Make sure to replace <YOUR_BEARER_TOKEN> with your actual authorization key.
Claude Code manages global MCP servers in the user-level configuration file:
~/.claude.json"mcpServers": {
"patchworld": {
"type": "http",
"url": "https://api.patchxr.io/mcp",
"headers": {
"Authorization": "Bearer <YOUR_BEARER_TOKEN>"
}
}
}
Google Antigravity CLI manages global MCP servers in its global configuration file:
~/.gemini/antigravity-cli/mcp_config.json{
"mcpServers": {
"patchworld": {
"serverUrl": "https://api.patchxr.io/mcp",
"headers": {
"Authorization": "Bearer <YOUR_BEARER_TOKEN>"
}
}
}
}
Codex stores MCP server settings in config.toml. The Codex app, Codex CLI, and Codex IDE extension share this configuration.
You can configure Patchworld globally:
~/.codex/config.tomlOr per project, if the project is trusted:
<your-project>/.codex/config.tomlAdd this configuration:
[mcp_servers.patchworld]
url = "https://api.patchxr.io/mcp"
bearer_token_env_var = "PATCHWORLD_API_KEY"
Then set the environment variable before starting Codex:
macOS / Linux
export PATCHWORLD_API_KEY="<YOUR_BEARER_TOKEN>"
Windows PowerShell
$env:PATCHWORLD_API_KEY="<YOUR_BEARER_TOKEN>"
Restart Codex after editing the config. In the Codex CLI or TUI, run:
/mcp
You should see patchworld listed as an available MCP server. In the Codex app or IDE extension, open the MCP settings panel to confirm the server is enabled.
Once connected, ask Codex to inspect or edit your running Patchworld scene, for example:
Use Patchworld to list the objects in my current scene.
The official PatchWorld ChatGPT app has been submitted and is currently pending review. Until it is approved and available in ChatGPT, you can use ChatGPT developer mode to create your own temporary development connector.
This workaround is intended for testing and personal use from ChatGPT web.
PatchWorld Dev.https://api.patchxr.io/mcp
PatchWorld Dev, and ask ChatGPT to use Patchworld.Example prompt:
Use PatchWorld to inspect my current scene and tell me what objects are connected.
Keep Patchworld open and run agent_control on in the in-app console before using the connector. If tools do not appear or calls time out, run:
agent_control publish
Then refresh the connector metadata in ChatGPT developer settings.
The Patchworld MCP server is compatible with any development tool or client that supports the Model Context Protocol (MCP). If you are using a different tool, you can simply ask your AI agent to help you connect it using the parameters provided in the configurations above.