Agentic Data Plane

Code Mode

Enable code mode on an MCP server to cut the token cost of serving a large tool catalog. Instead of loading every tool definition into context, agents search for the tools they need and run them through a lightweight JavaScript sandbox.

After reading this page, you will be able to:

  • Explain how code mode reduces tool-token usage for an MCP server

  • Enable code mode on an MCP server and find its code-mode endpoint

  • Use the search and execute tools to find and call tools through code mode

Code mode applies to one MCP server at a time. It is a token-reduction technique for a server with many tools, not a way to combine multiple servers behind one endpoint.

How code mode works

When you turn on code mode for an MCP server, AI Gateway creates a second MCP server named <server-name>-code, with the original server as its only member. It appears in the MCP servers list with the type Code MCP, and the original server and its endpoint are unchanged. If the original server is reachable at https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/<server-name>, the code-mode endpoint is the same path with a -code suffix:

https://aigw.<cluster-id>.clusters.rdpa.co/mcp/v1/<server-name>-code

Because the code-mode server is a server of its own:

  • Turning code mode off doesn’t remove it. To stop serving the code-mode endpoint, delete <server-name>-code.

  • You can’t delete the original server while <server-name>-code lists it as a member. Delete <server-name>-code first.

  • Saving with code mode on fails when another server already uses the name <server-name>-code, or when that name would be longer than 63 characters.

That endpoint exposes exactly two tools instead of the server’s full catalog:

search

Find tools in the underlying server’s catalog. Takes an optional query, a regular expression (Go RE2 syntax) matched against each tool’s name and description. It returns each match with its name, description, input schema, and, when the tool declares one, its output schema, or null when nothing matches. Omitting the query lists the entire catalog, which can be large, so use a narrow regex.

execute

Run JavaScript in a sandbox that is connected to the same MCP server. The value of the last expression in your code is returned as the tool result. Inside the sandbox, two synchronous host functions are available:

  • call_tool({name, arguments}): Invoke a tool on the server and return its output directly. It throws if the tool returns an error. A tool that reports a structured result gives you that result. Otherwise you get its text, parsed into the matching JavaScript value when it is valid JSON and returned as a string when it is not, or an array when the tool returned several blocks of text. Images, audio, and binary content are left out, and the execute result names what was left out so you can call that tool directly instead.

  • search_tools(query): Search the catalog by regex, the same as the search tool.

A typical interaction is: call search with a narrow regex to find candidate tools, read the returned input schema, then call execute with code that invokes one or more of those tools.

Sandbox constraints

The execute sandbox is isolated and intentionally limited. You cannot change these limits:

  • Code is capped at 64 KiB.

  • A single execute call can make at most 50 tool calls, counting call_tool and search_tools together, and runs for at most 10 seconds, tool calls included.

  • A program gets 64 MiB of memory, of which only about a third is available for its own data, so keep just the parts of each result you need.

  • A program whose result is larger than 4 MiB fails with an error instead of returning it. Filter or summarize in the program rather than returning everything.

  • Each run starts from a clean sandbox. A program has no network or file access, so call_tool is its only way to reach anything outside the sandbox.

  • The call_tool and search_tools host functions are synchronous, so do not use await on them. Top-level await and top-level return are syntax errors. To use await, wrap the code in an async function and make its promise the last expression, such as (async () => { ... })(). A promise the program returns is awaited.

  • Console output comes back alongside the result, up to 16 KiB, after which the result says that the rest was dropped. console.log, console.info, console.warn, console.error, and console.debug are all collected.

Calls that code mode makes to the underlying server run with the same identity and authentication as the server itself, including any per-user token vault credentials. Code mode does not widen what the server can reach.

When to use code mode

Turn on code mode when:

  • A server exposes a large tool catalog, so loading every tool definition on each request is expensive or pushes out other context.

  • An agent frequently performs multi-step tool sequences that you would rather run in one round trip instead of several model turns.

Leave it off for servers with only a handful of tools, where the overhead of searching and writing code outweighs the token savings of a small catalog.

Enable code mode

Enable code mode on the MCP server, then point your agent or client at the code-mode endpoint.

  1. Open MCP servers in the sidebar.

  2. Create a server, or open an existing one to edit it. See Create an MCP Server.

  3. Turn on Enable code mode.

  4. Save the server. The Code mode URL field on the server’s Connection tab shows the code-mode endpoint, which is the primary URL with a -code suffix.

  5. Configure your agent or MCP client to connect to the code-mode URL instead of the primary URL.

Test from the CLI

The --code-mode flag on rpk ai mcp-server tools targets the <server-name>-code server instead of the original server, so you can exercise search and execute directly. If you pass <server-name>-code as the server name, you don’t need the flag.

List the code-mode tools:

rpk ai mcp-server tools list <server-name> --code-mode

Search the underlying catalog:

rpk ai mcp-server tools call <server-name> search --code-mode \
  --args '{"query":"(?i)pull.*create"}'

Run code through the execute tool:

rpk ai mcp-server tools call <server-name> execute --code-mode \
  --args '{"code":"var pulls = call_tool({ name: \"github_pulls_list\", arguments: { owner: \"redpanda-data\", repo: \"redpanda\", state: \"open\" } }); JSON.stringify(pulls.map(function (p) { return { number: p.number, title: p.title }; }));"}'

The code calls a tool, shapes the result, and returns the value of its last expression. Because call_tool is synchronous, a single execute call can search, call several tools, and combine the results without extra model round trips.

Check your understanding

Answer each question, then expand it to compare.

A server exposes 200 tools. With code mode on, how many tools does an agent see at the code-mode endpoint?

Two: search and execute. The full catalog stays reachable, through search with a regular expression and through call_tool inside execute, but the agent no longer loads every tool definition into context.

Can you put three MCP servers behind one code-mode endpoint?

No. Code mode applies to one MCP server at a time. It reduces the token cost of a large catalog on that server, and it isn’t a way to combine servers behind one endpoint.

Your execute code reads await call_tool({…​}). What happens?

It fails. The call_tool and search_tools functions are synchronous, and top-level await is a syntax error. Call the function directly and make the value you want the last expression in the code. When you need await for something else, wrap the code in an async function and make its promise the last expression.

Does code mode let an agent reach anything the underlying server can’t?

No. Calls made through code mode run with the same identity and authentication as the server itself, including any per-user token vault credentials.

Next steps