---
title: Code Mode
latest-operator-version: v26.2.6
latest-console-tag: v3.14.0
latest-connect-version: 4.118.0
latest-redpanda-tag: v26.2.7
docname: code-mode
page-component-name: agentic-data-plane
page-version: master
page-component-version: master
page-component-title: Agentic Data Plane
page-relative-src-path: code-mode.adoc
page-edit-url: https://github.com/redpanda-data/adp-docs/edit/main/modules/gateway/pages/code-mode.adoc
description: A Code MCP server gives agents two tools, search and execute, in place of the full tool catalogs of one or more MCP servers. It cuts the token cost of tool-heavy servers.
page-topic-type: how-to
personas: agent_builder, platform_engineer
learning-objective-1: Explain how code mode reduces tool-token usage for an MCP server
learning-objective-2: Create a Code MCP server and find its endpoint
learning-objective-3: Use the search and execute tools to find and call tools through code mode
page-git-created-date: "2026-06-09"
page-git-modified-date: "2026-11-06"
page-generated-content: none
---

# Code Mode

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [agentic-data-plane-full.txt](https://docs.redpanda.com/agentic-data-plane-full.txt)

<!-- Source: https://docs.redpanda.com/agentic-data-plane/gateway/code-mode.md -->

Create a Code MCP server in front of one or more [MCP servers](https://docs.redpanda.com/home/glossary/#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

-   Create a Code MCP server and find its endpoint

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


> 📝 **NOTE**
>
> A Code MCP server is itself an MCP server, with its own name and endpoint. It can include up to 50 managed or remote servers as members, and its two tools work across all of them.

## How code mode works

A Code MCP server is an MCP server of its own that lists other servers as members, up to 50 managed or remote servers. It appears in the MCP servers list with the type Code MCP, and the member servers and their endpoints are unchanged. The Code MCP serves its own endpoint:

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

Because the Code MCP is a server of its own:

-   Deleting it stops serving its endpoint and changes nothing on its members.

-   You can’t delete a member server while a Code MCP lists it. Remove the member from the Code MCP, or delete the Code MCP, first.


A server created with the deprecated `code_mode` configuration field gets a companion Code MCP named `<server-name>-code`, with that server as its only member.

A remote server that uses token passthrough can’t be a member. Through a Code MCP, the caller’s token would also work for the Code MCP and its other members, so saving the Code MCP fails. Switch that server to another authentication method first.

The Code MCP’s endpoint exposes exactly two tools instead of the members' full catalogs:

**`search`**

Find tools in the member servers' catalogs. Takes an optional `query`, a regular expression (Go RE2 syntax) matched against each tool’s name and description. It returns each match with the member server it belongs to, 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 member servers. 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({server, name, arguments})`: Invoke a member server’s tool and return its output directly. `server` names the member, as `search` returns it. You can leave it out when only one member has a tool with that name. When several members do, the call fails until you pass `server`. 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 a member server run with the same identity and authentication as that server itself, including any per-user [token vault](https://docs.redpanda.com/home/glossary/#token-vault) credentials. Code mode does not widen what a member server can reach.

## When to use code mode

Create a Code MCP server 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.

-   An agent needs tools from several servers in one program, so you want one endpoint that can search and call all of them.


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

## Create a Code MCP server

Create the Code MCP, then point your agent or client at its endpoint.

1.  Open **MCP servers** in the sidebar.

2.  Click **Add MCP server**, then click the **Code MCP** card.

3.  Name the server, and in the `Members` section select the servers it includes, up to 50.

4.  Click **Create Code MCP**. The new server’s **Overview** tab shows its members and its endpoint.

5.  Configure your agent or [MCP client](https://docs.redpanda.com/home/glossary/#mcp-client) to connect to the Code MCP’s URL instead of a member’s URL.


To add an existing server to a Code MCP from that server’s page, click **Add to Code MCP** on its **Overview** tab, then choose an existing Code MCP or **New Code MCP**.

## Test from the CLI

A Code MCP server is called like any other server, so pass its own name to `rpk ai mcp-server tools` to exercise `search` and `execute` directly. The `--code-mode` flag targets the companion server named `<server-name>-code` that the deprecated code-mode configuration creates, so you can keep passing the original server’s name for one of those.

List the code-mode tools:

```bash
rpk ai mcp-server tools list <code-mcp-name>
```

Search the members' catalogs:

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

Run code through the `execute` tool:

```bash
rpk ai mcp-server tools call <code-mcp-name> execute \
  --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 Code MCP’s only member exposes 200 tools. How many tools does an agent see at the Code MCP’s 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?

Yes. Create a Code MCP server and select all three as members. A Code MCP includes up to 50 managed or remote servers, and its `search` and `execute` tools work across every member’s catalog.

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 its member servers can’t?

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

## Next steps

-   [Create an MCP Server](https://docs.redpanda.com/agentic-data-plane/connect/create-server/)

-   [How MCP Servers Work](https://docs.redpanda.com/agentic-data-plane/connect/mcp-overview/)

-   [Test MCP Tools](https://docs.redpanda.com/agentic-data-plane/connect/test-tools/)