CodeModeTOON

CodeModeTOON MCP Server is a compact orchestration layer for scalable, stateful AI workflows. It combines TOON compression with lazy-loading of MCP servers to minimize token usage while keeping complex workflows efficient and maintainable.

How to use

To use CodeModeTOON with your MCP client, install the MCP server as a local, stdio-based service and connect your client to it via the standard MCP bridge. You will typically run the local CodeModeTOON process and route your tool calls through it. The server lazily starts tools on demand, compresses results with TOON, and returns compact, structured data that you can feed back into your agent loops. When you need to execute multiple tools, prefer orchestrating them through predefined workflows to save tokens and reduce latency. If the agent needs a new capability, it can discover tools lazily and then configure usage through the provided APIs.

How to install

Prerequisites: you need Node.js installed on your system to run the MCP server via npx. You also use a local MCP client that can communicate through the CodeModeTOON bridge.

Option 1 — One‑Click (Cursor): use the one‑click installer to set up CodeModeTOON as an MCP server in your Cursor environment. Follow the one‑click flow to configure and connect your client to the local MCP bridge.

Option 2 — Manual Setup (local stdio server): create or edit your MCP config file so your client can start the server locally.

Configuration

A typical local setup runs CodeModeTOON through npx and loads its configuration from your MCP client. The following configuration snippet defines a stdio MCP server named code_mode_toon and wires the necessary environment variable to locate the MCP config.

{
  "mcpServers": {
    "code_mode_toon": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "code-mode-toon"],
      "env": {
        "CODE_MODE_TOON_CONFIG": "~/.cursor/mcp.json"
      }
    }
  }
}

Security and best practices

The CodeModeTOON runtime uses the Node.js vm module for sandboxed-like execution of MCP tool access. It is suitable for personal or trusted assistant use but is not designed for multi-tenant public services. Keep the config file private and restrict access to your local machine or trusted environments.

Troubleshooting

If you encounter issues starting the MCP server, verify that the command and arguments exactly match the config, and that the CODE_MODE_TOON_CONFIG path points to a valid MCP configuration file. Use the provided tooling hints to discover new tools when needed, and ensure you are using the correct server name when calling APIs.

Performance and usage notes

CodeModeTOON focuses on stateful execution and context efficiency. Expect token cost reductions when processing large structured data, such as logs or inventories, due to TOON compression and careful data shaping. When synthesizing results, prefer server-side synthesis to keep context lean.

Workflows and prompts

CodeModeTOON supports server‑side Workflows—pre-defined TypeScript modules that orchestrate multiple MCP tools. Use the built‑in prompts and meta‑tools to guide when to run workflows, how to batch tool calls, and how to recover from errors with actionable hints.

License

CodeModeTOON is distributed under the MIT License. See the license text for details.

Notes on usage with Claude Skills

You can enable a Claude Skill to optimize usage of CodeModeTOON, including a workflow expert that guides when to use code, workflows, or direct calls. Install the skill by placing the skill package into your Claude skills directory or by importing it in the Claude desktop app.

Available tools

TOON.encode

Encodes data into a highly compressed TOON format to reduce token usage when returning large structured responses.

get_tool_api

Retrieves the API object for a given MCP server so you can call its endpoints programmatically.

execute_code

Executes a block of code in a controlled environment and returns results along with usage metrics.

search_tools

Searches available MCP tools when a capability is not immediately visible to the agent.

list_workflows

Lists pre-defined server-side workflows that orchestrate multiple MCP tools.