> For the complete documentation index, see [llms.txt](https://docs.quickclient.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.quickclient.cc/en/extras/mcp.md). # MCP for AI agents How to connect an AI agent to the running game so it can write and test scripts. Quick has a built-in MCP server. Through it an AI agent connects to the running game and can write scripts on its own. Claude Code, Codex, OpenCode, Cursor, Windsurf, Gemini CLI and VS Code are supported. The agent reads sources, writes jars, sees compile errors and console lines, turns scripts on and off, and reads the API reference. You do not need an IDE for this, and you do not have to pack anything by hand. ## Turning it on 1. Open the Quick menu → gear → **MCP**. 2. Turn on the **Enabled** switch. The server listens only on `127.0.0.1`, the port and token are chosen at random and saved. 3. In the **Agent** row, pick your agent. The **Configure** button adds the server to its config: for Claude Code it runs `claude mcp add`, for Codex it appends a block to `config.toml`, for the others it adds an entry to their JSON. 4. If automatic setup did not work, the **Copy command/config** and **Copy address and token** buttons appear. In that case paste the values by hand. | Button | What it does | | -------------------- | -------------------------------------------------------------- | | `Enabled` | starts or stops the server, the state is saved | | `Address` | copies `127.0.0.1:` on click | | `Token` | copies the token on click | | `Agent` | switches to the next agent on click | | `Configure ` | automatic setup; if the server is off, turns it on first | | `New port and token` | issues new access; agent configs need to be updated afterwards | If you set up the agent yourself, here is what you need. The server address is `http://127.0.0.1:/mcp`, transport Streamable HTTP, JSON-RPC 2.0. There is one check: the `Authorization: Bearer ` header. Without it the server answers 401. For Claude Code the manual setup looks like this (replace `PORT` and `TOKEN` with the values from the menu): ```bash claude mcp add --scope user --transport http quickclient http://127.0.0.1:PORT/mcp --header "Authorization: Bearer TOKEN" ``` ## Tools These are the tools the agent can use through the server: | Tool | What it does | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `scripts_list` | list of scripts: name, jar, enabled, crashed, description, number of settings | | `script_read` | script sources and the list of its resources | | `script_write` | writes files into the jar (creates the jar if it does not exist) and reloads right away; returns errors and the latest console lines | | `scripts_reload` | reloads all scripts | | `script_toggle` | turns a script on or off | | `script_settings` | settings with their current values | | `script_setting_set` | changes a setting value by id | | `console_read` | console log; `since` reads from a given position, `level` filters by info/warn/error | | `console_clear` | clears the console | | `api_docs` | without a path returns a short guide and the list of SDK files, with a path returns the file text, for example `hex/script/api/Script.java` | | `client_state` | player, server, position, health, open screen, number of enabled scripts | Paths in `script_write` are written as inside the jar: `java/my/Foo.java` or just `my/Foo.java`, mixins as `mixin/scriptmixin/…`, resources as `resources/…`. Everything else in the jar stays as it was, and extra files can be deleted with the `remove` list. A typical agent loop: `scripts_list` → `script_read` → edit → `script_write` → if the response has errors, edit again → `script_toggle` → `console_read` with `since` from the previous response, to see only new lines. The agent cannot play for you. No tool moves the player, opens screens or clicks blocks. The agent only has access to the scripts folder, the console and the reference. It has no access to accounts, Quick configs or other files on disk. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.quickclient.cc/en/extras/mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.