Code Mode
Create a Code MCP server in front of one or more MCP servers 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
|
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:
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.servernames the member, assearchreturns 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 passserver. 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 theexecuteresult names what was left out so you can call that tool directly instead. -
search_tools(query): Search the catalog by regex, the same as thesearchtool.
-
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
executecall can make at most 50 tool calls, countingcall_toolandsearch_toolstogether, 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_toolis its only way to reach anything outside the sandbox. -
The
call_toolandsearch_toolshost functions are synchronous, so do not useawaiton them. Top-levelawaitand top-levelreturnare syntax errors. To useawait, 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, andconsole.debugare 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 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.
-
Open MCP servers in the sidebar.
-
Click Add MCP server, then click the Code MCP card.
-
Name the server, and in the
Memberssection select the servers it includes, up to 50. -
Click Create Code MCP. The new server’s Overview tab shows its members and its endpoint.
-
Configure your agent or 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:
rpk ai mcp-server tools list <code-mcp-name>
Search the members' catalogs:
rpk ai mcp-server tools call <code-mcp-name> search \
--args '{"query":"(?i)pull.*create"}'
Run code through the execute tool:
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.