Guide

What Is Code Mode for MCP?

Code Mode allows an AI agent to work with thousands of tools without consuming any more context than a static fixed context cost of two (2) tools: search and execute.

· Erik Jonsson Thorén, Founder, Gatana

Short answer: Code Mode allows an AI agent to work with thousands of tools without consuming any more context than a static fixed context cost of two (2) tools: search_tools and execute_code. The agent starts with search_tools and then provides a JavaScript snippet to execute_code. The JavaScript snippet is being executed in an environment with access to those 1000:s of tools.

The problem code mode solves

As the number of tools increases, which they tend to do over time, the agent context increases as well. This means more cost ($) and less precision for the large-language-model powering your agent.

The tool list. Every tool definition that the agent receives costs prompt tokens on every request. A definition is a name, a description and a JSON schema. A GitHub server alone has dozens of tools. An organization with ten servers behind a gateway can have several hundred. The agent sends the full list again on every turn of the conversation.

The results. In the usual MCP setup, every tool result enters the context of the model. A page of 500 orders is about 15,000 tokens. The model reads it, keeps it, and re-sends it on every later turn. A task over 10,000 orders needs 20 such pages. The model must also do the arithmetic on the data in the open, token by token. Models estimate. They do not count.

Tool search solves the first cost. Code mode solves both.

How code mode works

The gateway answers the tool list request of the agent with two tools.

search_tools takes a query in plain words, such as “github pull request” or “send email”. It matches the words against the names and descriptions of the tools that the caller may use. It returns the best matches, up to 15. Each match has the name, the description, the arguments and the shape of the result. Without a query, it returns a summary: the servers, and the first tool names.

execute_code takes TypeScript or JavaScript. The code calls tools through one object, codemode, with the server and the tool as names: codemode.github.getPullRequest({ owner, repo, pull_number }). Each call returns a promise. The code ends with a return statement, or logs what it wants to report. The gateway runs the code in a sandbox and sends back the console output and the returned value.

A run looks like this. The agent receives a task: the total revenue for each region over all orders. It searches:

search_tools({ query: "orders" })

The answer names one tool, shop.listOrders, with the arguments page and pageSize and a result of the shape { orders: [...], nextPage: number | null }. The agent writes:

const totals: Record<string, number> = {};
let page: number | null = 1;
while (page) {
  const { orders, nextPage } = await codemode.shop.listOrders({ page, pageSize: 500 });
  for (const order of orders) {
    totals[order.region] = (totals[order.region] ?? 0) + order.amount;
  }
  page = nextPage;
}
return totals;

The sandbox makes 20 tool calls, reads 10,000 rows and sums them. The model receives one object with a few keys. In our benchmark, this task cost 30,458 prompt tokens in code mode against 1.33 million with direct calls. The answer was correct in every code mode run.

What changes for the agent

Nothing in the connection. The agent connects to the same MCP endpoint with the same credentials. The difference is in the answer to the tool list request: two tools instead of hundreds. The model reads the descriptions of the two tools and learns the pattern from them. Any MCP client that can call a tool can use code mode. No plugin on the client side is necessary.

The model does more of the work. It must select the right tool from the search results, read the shape of the result, and write a loop that handles pages and errors. The gateway helps with this. A wrong tool name produces an error that names the closest real tool. A run that fails reports the shape of every result that it received. A run that returns nothing is told to end with return.

What stays the same: identity, access and audit

Code mode moves the loop into the gateway. The person who runs it stays the same.

  • Identity. The sandbox receives a short-lived token for the person behind the agent. The token carries the profiles and the server restrictions of the session. Every tool call from the code goes back through the gateway under that identity.
  • Access. The code can only call the tools that the caller may see. Server shares, profiles, token scopes and tool firewall rules apply to each call, as for a direct call. A name outside that set fails inside the sandbox. It never reaches a tool.
  • Audit. Each tool call from the sandbox is a record in the audit log, under the same person and credential as the execute_code call that ran the code. A refused name becomes a record of its own, with the outcome denied or not-found and the reason. The code cannot hide the attempt by catching the error.

Isolation

The code runs in a Node.js virtual machine context with a fixed set of globals: the standard data types, Math, JSON, Date, Promise, Map, Set and the typed arrays. It cannot use fetch, require, the file system or the process object. The only way out of the sandbox is a tool call through the codemode object. In Gatana Cloud, the worker that hosts the sandbox is a separate pod for each organization. It runs in a Kata Containers virtual machine. The worker starts when the agent first searches, so that it is ready when the code arrives.

What it saves

We measured code mode against direct tool calls on 5 October 2026 with DeepSeek-V4.1-Flash. Three tasks, five runs each per mode, the same model and the same correctness check. The numbers are medians.

Task Direct Code mode
Revenue by region, 10,000 orders 2 of 5 correct, 1,330,460 tokens, 617 s 5 of 5 correct, 30,458 tokens, 12 s
Word counts, 40 documents 0 of 5 correct, 242,630 tokens, 318 s 5 of 5 correct, 59,153 tokens, 19 s
Five largest of 500 files 5 of 5 correct, 31,110 tokens, 6 s 5 of 5 correct, 17,670 tokens, 9 s

The point is not only the tokens. On the two large tasks, direct calls were wrong in 8 of 10 runs. Code mode was wrong in none. The model fetched the data in both modes. Only in code mode could it do the arithmetic on it. The full method, the limits and the raw data are on the measurements page.

When to use code mode

Use code mode when at least one of these statements is true:

  • The tool list is large. Gatana’s default threshold is 70 tools.
  • A task walks through thousands of rows or dozens of documents.
  • A task chains several tools, and the intermediate results are of no interest to the model.
  • The result needs arithmetic, counting or sorting over the data.

Call the tools directly when one result fits in a few thousand tokens. The model reads it without trouble. Code mode would spend two extra turns, one to search and one to write the code. In the benchmark, the small task was correct in both modes, and direct was a little faster. Size the task, not the tool.

How to switch it on in Gatana

Code mode is served by the built-in codemode server. It is included in the Pro and Enterprise plans. Three switches exist:

  1. Automatically, by tool count. Under Settings, Features, enable Automatic Code Mode and set a threshold. When the tool list of a request exceeds the threshold, the gateway answers with the code mode tools instead. The default is 70. Set it to 0 to use code mode always.
  2. By profile. Set Force Code Mode on a profile. Every session that uses the profile runs in code mode, for all servers that the person may use, not only the servers in the profile. Saving the flag adds the codemode server to the profile. If the server is not installed for the organization yet, saving installs it.
  3. By URL. Add ?codemode to the MCP URL: https://gatana.ai/mcp?codemode. Use this to test one agent before you change a setting for everyone.

Tools that a profile promotes stay listed next to the two code mode tools. Use this for a few tools that the agent calls often. They remain one direct call while the rest is behind execute_code.

Limits to know

  • The search matches keywords in names and descriptions. It is not semantic. A query with other words than the tool description finds nothing. The agent then tries other words, or lists the servers with an empty query.
  • The gateway waits at most 120 seconds for one run. Split a longer loop into several calls.
  • Tool results enter the sandbox uncompressed. The memory of the sandbox bounds how much data one run can hold.
  • The code must be correct. A model that guesses the shape of a result writes a loop that fails. The error report contains the real shapes, and the next attempt usually succeeds. In the benchmark, one code mode run on the small task used 30 times the median tokens.

Where to go next

The code mode page in our documentation shows the exact output of search_tools and the enabling steps. The benchmark post has all 30 runs, and the measurements page has the raw data with its date. The pattern comes from Cloudflare’s Code Mode work. Anthropic describes the same idea for MCP in Code execution with MCP.

FAQ

Questions, answered.

What is code mode in MCP?

Code mode is a way to give an agent many tools at a fixed cost. The gateway lists two tools instead of hundreds: search_tools and execute_code. The agent searches for the tools that it needs and writes a short program that calls them. The program runs in a sandbox inside the gateway. Only the result reaches the model.

Does my agent need a change to use code mode?

No. The agent connects to the same MCP endpoint. The gateway answers the tool list request with the two code mode tools instead of the full list. Any MCP client that can call a tool can use them. The model reads the descriptions of the two tools and learns the pattern from them.

Can the code call tools that the person may not use?

No. The sandbox receives a short-lived token for the person behind the agent. Every tool call from the code goes back through the gateway under that identity. The same server shares, profiles, token scopes and firewall rules apply as for a direct call. A refused name is recorded in the audit log, even if the code catches the error.

Which language does the code use, and what can it reach?

TypeScript or JavaScript. The code runs in a Node.js virtual machine context with the standard data types, Math, JSON, Date and Promise. It cannot use fetch, require, the file system or the process object. The only way out is a tool call through the codemode object. In Gatana Cloud, each organization gets its own Kata Containers virtual machine.

When does code mode not help?

When one tool result fits in a few thousand tokens. The model can read such a result directly. Code mode then costs two extra turns, one to search and one to write the code. In our benchmark, the small task was correct in both modes and direct was a little faster. Size the task, not the tool.

How do I switch on code mode in Gatana?

Three ways. Under Settings, Features, enable Automatic Code Mode and set a tool count threshold. The default is 70. Zero means always. Or set Force Code Mode on a profile. Or add ?codemode to the MCP URL. Code mode is included in the Pro and Enterprise plans. Tools that a profile promotes stay listed next to the code mode tools.

All guides