# Code Mode: calling MCP and UTCP tools by writing TypeScript instead of emitting JSON

> Code Mode is a TypeScript and Python library that gives an agent one tool that executes code with access to every registered tool. It fits agents that already write code well and struggle with large tool menus.

**universal-tool-calling-protocol/code-mode** — 🔌 Plug-and-play library to enable agents to call MCP and UTCP tools via code execution. 

- Repository: https://github.com/universal-tool-calling-protocol/code-mode
- Stars: 1,571 · Forks: 108
- Language: TypeScript
- License: MPL-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/universal-tool-calling-protocol-code-mode

## The problem Code Mode targets: tool menus that outgrow the prompt

A conventional agent loop exposes tools as function definitions and asks the model to emit a JSON call for one of them. That works at five tools. At five hundred it does not. Every definition occupies context, every call is a separate round trip, and the model has to re-read the whole conversation between steps. The README puts the trade plainly: instead of exposing hundreds of tools directly, give the model one tool that executes TypeScript with access to the whole toolkit.

The intended user is whoever maintains an agent that already talks to MCP servers or HTTP APIs and has watched the orchestration layer become the bottleneck. Code Mode is not a model and not a server. It is a client library, published as @utcp/code-mode on npm, that sits between your agent and the tool servers you already run. The repository also ships a Python library under python-library/, added in v1.0.6.

The claim is not that the model gets smarter. It is that writing a short program is a task LLMs are better at than emitting a sequence of structured calls, and that one program can replace many calls.

## How Code Mode executes a tool chain in a Node.js isolate

The mechanism is a registration step followed by an execution step. You register a manual, which is a description of where tools live: an MCP server, an HTTP API with auto-discovery, a local JSON or YAML file, or a CLI. The library then exposes those tools as callable objects inside a sandbox. When you pass a string of TypeScript to callToolChain, that string runs in the sandbox with the registered namespaces in scope, and whatever the code returns comes back as result.

The README's own example chains three GitHub calls inside one string and returns a small object with a title, a comment count, and an approval count. The comment next to it says a single API call replaces 15 or more traditional tool calls. That is the whole architectural bet: the intermediate values never leave the sandbox, so the model never has to see them.

Two supporting pieces matter. searchTools takes a natural-language query and returns matching tools, which the README frames as three relevant tools instead of 500 definitions. And the library auto-generates TypeScript interfaces for registered tools, so the code the model writes is typed against real input shapes rather than guessed. The README describes the sandbox as Node.js isolates, with configurable execution limits to stop runaway code, full console output capture, and no external dependencies beyond the registered servers.

## Installing Code Mode and running a first tool chain

Installation is a single npm command. The package is scoped, so the name matters.

```bash
npm install @utcp/code-mode
```

The README's three-line example shows the shape of a first program: create the client, register a manual, call a tool chain. Registration details depend on which server you point at, and the README leaves the MCP config inline as a comment rather than spelling it out, so expect to consult the manual documentation for the exact object.

```typescript
import { CodeModeUtcpClient } from '@utcp/code-mode';

const client = await CodeModeUtcpClient.create();
await client.registerManual({ name: 'github', /* MCP config */ });
const { result } = await client.callToolChain(`/* TypeScript */`);
```

A more realistic first run is the discovery path. Ask for tools by description before writing any chain, then use the names that come back. The README shows searchTools returning a filtered set for a query like 'github pull request'.

```typescript
const tools = await client.searchTools('github pull request');
```

If your agent has shell access, the repository recommends the separate CLI package instead of the library API. The README points the agent at a built-in guide with npx -y @utcp/code-mode-cli prompt, then uses search and run subcommands, and a login subcommand for interactive OAuth that writes a token to .env. The README states the CLI should be preferred whenever the agent can run shell commands, and the MCP server reserved for MCP-only clients such as Claude Desktop.

## Where Code Mode is the wrong tool

The design assumes your runtime can execute JavaScript or Python. If your agent runs in a constrained environment with no interpreter, or a policy that forbids arbitrary code execution, the library has nothing to offer. That is not a tuning problem; the execution step is the product.

The second constraint is the sandbox itself. The README describes Node.js isolates and zero external dependencies, meaning tools are reachable only through registered servers. That is a boundary you have to trust and, in a regulated deployment, verify yourself. The README does not document the isolation guarantees in detail, does not describe a resource limit beyond timeouts, and does not discuss rollback or audit trails for executed code. If you need a per-call approval gate before anything runs, that is not what this is.

The third is maturity. The first public release was v1.0.5 on 2025-11-15, and Python support arrived in v1.0.6 on 2025-11-23. The last push to the repository was on 2026-08-25. That is a young project with a short release history, so treat the API surface as something that can still move.

Finally, the README's own benchmark table comes from a linked third-party Python study, not from measurements the project ran. The figures there (67%, 75%, 88% faster across scenario complexities, and a $9,536/year saving at 1,000 scenarios per day) are the study author's numbers under that study's assumptions. Reproduce them against your own workloads before quoting them internally.

## Code Mode versus plain function calling and versus a hosted code-mode runtime

The nearest alternative is the thing Code Mode replaces: standard function calling, where the model emits a JSON object naming a tool and its arguments, and your loop dispatches it. The difference is where the orchestration lives. With function calling, your application code owns the sequence, and every step is a model round trip. With Code Mode, the model owns the sequence inside one execution, and your application sees one result. Function calling is simpler to audit step by step and works with any model that supports tool use. Code Mode demands a code-capable model and an execution sandbox.

The README also points at Cloudflare's code mode write-up and Anthropic's engineering post on code execution with MCP as prior art, and an Apple CodeAct paper. Those are hosted or platform-level takes on the same idea. The practical difference is deployment: Code Mode is a library you install next to your own agent, so the tools stay in your infrastructure and the credentials stay in your process. A hosted runtime makes that someone else's operational problem and someone else's trust boundary. The README does not compare itself to those systems on latency, cost, or isolation, so the choice comes down to where you are willing to run code.

Within the same repository there is also a split worth knowing. The MCP server under code-mode-mcp/ wraps the same engine for MCP-only clients. The README says both wrap the same @utcp/code-mode engine, so the difference is transport, not behaviour.

## Maintenance, versioning and the MPL-2.0 licence

The repository is not archived, and the last push was on 2026-08-25. The published releases are v1.0.5 and v1.0.6, both from November 2025, so the release cadence is slower than the commit history. Before an upgrade, read the release notes for the version you are moving to; the README does not document a deprecation policy or a migration path between minor versions, which is the practical risk of adopting at 1.x.

Upgrade cost is mostly the sandbox contract. If a future version changes how manuals are registered or how tool namespaces are exposed inside the sandbox, the TypeScript strings your agent generates are the code that breaks, and those strings may be produced at runtime rather than checked into your repository. Pin the package version and keep a small set of representative tool chains in your test suite so a version bump fails loudly.

The licence is MPL-2.0, a file-level copyleft licence. Modifications to files that are part of the covered source must be made available under the same licence, while larger works that combine the library with other code can generally be distributed under other terms. This is a summary, not legal advice; if you plan to modify the library itself or embed it in a distributed product, have your own counsel read the LICENSE file in the repository root.

## Conclusion

Adopt Code Mode if your agent already generates code reliably and your tool menu has grown past the point where dumping every schema into the prompt still works. Skip it if your runtime cannot execute JavaScript or Python at all, or if you need a stable public API surface: the first public release was v1.0.5 in November 2025, so pin a version and read the changelog before upgrading. Verify first that your deployment can give the sandbox the isolation you need, and that the timeout default suits your workloads, since the README lists configurable execution limits but does not state a default.

## FAQ

### How do I use Code Mode?

Install @utcp/code-mode, create a client with CodeModeUtcpClient.create(), register a manual pointing at an MCP, HTTP, file or CLI source, then pass a TypeScript string to callToolChain. The README presents this as a three-line setup.

### What is code mode in AI?

It is an approach where the model writes and executes code against registered tools instead of emitting one JSON function call per step. Code Mode implements this as a library that runs the code in a Node.js isolate with access to your tool servers.

### What is code mode MCP?

MCP is one of the protocols Code Mode can register as a tool source, alongside HTTP, file and CLI, selected through call_template_type. The repository also ships an MCP server under code-mode-mcp/ for clients that can only speak MCP, such as Claude Desktop.

### How does MCP compare with code mode?

They are not competing layers. MCP is a protocol for exposing tools; Code Mode is a client that consumes MCP servers by letting the model write code against them. The README recommends the CLI over the MCP server whenever the agent has shell access, but both wrap the same engine.

## Sources

- [Issues](https://github.com/universal-tool-calling-protocol/code-mode/issues)
- [License: MPL-2.0](https://github.com/universal-tool-calling-protocol/code-mode/blob/main/LICENSE)
- [README](https://github.com/universal-tool-calling-protocol/code-mode/blob/main/README.md)
- [Releases](https://github.com/universal-tool-calling-protocol/code-mode/releases)
- [universal-tool-calling-protocol/code-mode on GitHub](https://github.com/universal-tool-calling-protocol/code-mode)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/universal-tool-calling-protocol-code-mode