# UTCP Code-Mode

> An open-source TypeScript library that enables AI agents to call MCP and UTCP tools via code execution instead of traditional JSON function calling, reducing API round trips significantly.

UTCP Code-Mode is an open-source TypeScript library published under the Mozilla Public License 2.0 that lets AI agents execute multi-step tool workflows as a single block of TypeScript code rather than issuing individual JSON function calls. It is part of the Universal Tool Calling Protocol (UTCP) ecosystem, which provides a lightweight standard for AI agents to discover and call tools directly using their native protocols without wrapper servers.

## What It Is

Code-Mode reframes how AI agents interact with tools: instead of exposing hundreds of discrete tool definitions and asking the model to orchestrate them one at a time, it gives the agent a single `callToolChain` method that accepts a TypeScript code string and executes it inside a secure Node.js VM sandbox. The agent writes code that calls tools as async functions, chains operations, processes data in-sandbox, and returns a structured result — all in one request. The library auto-generates TypeScript namespace interfaces for every registered tool, enabling IDE IntelliSense and runtime introspection.

## Why Code Execution Beats Traditional Tool Calling

The README cites research from Apple, Cloudflare, and Anthropic as evidence that code-based tool calling is more efficient than the traditional "dump function info → extract JSON → call → repeat" loop. An independent Python benchmark study (linked in the README) tested 16 realistic scenarios across financial, DevOps, data processing, and business automation workflows and reported the following improvements over traditional tool calling:

- **Simple workflows (2–3 tools):** 67% fewer iterations
- **Medium workflows (4–7 tools):** 75% fewer iterations
- **Complex workflows (8+ tools):** 88% fewer iterations

The benchmark authors attribute the gains to batching (one code block replaces multiple API calls), cognitive efficiency (LLMs write code more reliably than they orchestrate tool JSON), and elimination of context re-processing between operations.

## Architecture and Protocol Support

Code-Mode is built on top of the UTCP client and uses a plugin-based architecture. Each communication protocol is a separate npm package that registers itself as a side effect of being imported:

- **HTTP** (`@utcp/http`) — REST APIs with auto-discovery and OpenAPI conversion
- **MCP** (`@utcp/mcp`) — Model Context Protocol servers via stdio or SSE
- **CLI** (`@utcp/cli`) — Command-line tool execution
- **Text/File** (`@utcp/text`) — Local JSON/YAML UTCP manuals

Multiple protocols can be mixed in a single `callToolChain` execution. The sandbox enforces no filesystem access, no external network calls outside registered servers, and configurable timeouts (default 30 seconds).

## Deployment Paths

The library ships three consumption modes:

1. **Direct TypeScript/Node.js** — `npm install @utcp/code-mode` and use `CodeModeUtcpClient` programmatically.
2. **CLI (`@utcp/code-mode-cli`)** — Preferred for shell-capable agents (Claude Code, Cursor, Codex). The agent self-configures by writing a `.utcp_config.json` and drives discovery and execution from the shell via `npx -y @utcp/code-mode-cli`.
3. **MCP Server (`@utcp/code-mode-mcp`)** — For MCP-only clients such as Claude Desktop; configured via the standard `mcpServers` JSON block and exposes `call_tool_chain` as an MCP tool.

## Update: v1.0.6 — Python Support Added

The latest release (v1.0.6, published November 2025) added Python support alongside the existing TypeScript implementation, making Code-Mode available in both languages. The UTCP organization also maintains separate language-specific client packages for Python, TypeScript, and Go. The repository had 1,571 stars and 108 forks as of the data snapshot, with active development continuing through mid-2026 according to the GitHub metadata.

## Features
- Execute multi-step tool workflows as a single TypeScript code block
- Secure Node.js VM sandboxing for code execution
- Auto-generated TypeScript namespace interfaces for all registered tools
- Progressive tool discovery via natural language search
- Multi-protocol support: HTTP, MCP, CLI, Text/File
- OpenAPI spec auto-conversion to UTCP manuals
- Built-in console output capture and error handling
- Configurable execution timeouts
- Runtime interface introspection via __interfaces and __getToolInterface()
- CLI mode for shell-capable agents (Claude Code, Cursor, Codex)
- MCP server mode for Claude Desktop and MCP-only clients
- AI agent prompt template included (AGENT_PROMPT_TEMPLATE)
- Context-efficient in-sandbox data processing
- Interactive OAuth login support via CLI

## Integrations
MCP (Model Context Protocol), OpenAPI, HTTP REST APIs, CLI tools, GitHub MCP server, Claude Desktop, Claude Code, Cursor, Codex, OpenAI GPT-4, Slack, Notion, GraphQL

## Platforms
LINUX, API, VSC_EXTENSION, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v1.0.6

## Links
- Website: https://github.com/universal-tool-calling-protocol/code-mode
- Documentation: https://www.utcp.io
- Repository: https://github.com/universal-tool-calling-protocol/code-mode
- EveryDev.ai: https://www.everydev.ai/tools/utcp-code-mode