For the complete documentation index, see llms.txt.
Skip to main content

Use Code Mode

Use Code Mode in reShapr 1.1.0 when an agent needs to search a large API, chain calls, or reduce results before returning them to the model. Instead of loading every Tool definition, the client discovers just the operations it needs and submits JavaScript to the proxy.

This follows the code-execution-with-MCP pattern described by Cloudflare and Anthropic: present Tools as a code API, compose calls in code, and process intermediate results before returning an answer to the model. In reShapr, execution is server-side in the proxy; the client uses the Exposition's MCP Tools rather than installing an agent-side execution SDK or enabling a provider-specific code execution API.

Unlike a Scripted Custom Tool, whose script is supplied by the Service author, Code Mode accepts code supplied by the MCP client at request time. It is programmable execution, not a no-code workflow.

For the discovery and execution flows, sandbox security model, and guardrail boundaries, see Code Mode: Flows and Security Boundaries.

Prerequisites​

  • A control plane and proxy running reShapr 1.1.0.
  • An existing Service, Configuration Plan, and Exposition, with a working read-only Tool call.
  • Permission to edit the Plan and an MCP client that can call Tools and generate JavaScript.
  • For GitOps configuration, controllers 0.0.4 and the matching ConfigurationPlan CRD installed explicitly. Helm does not upgrade existing CRDs.

Choose the Tool exposure mode​

Open the Configuration Plan in the Web UI and set its Tool exposure mode, then save. The same field is toolExposureMode in the public API and ConfigurationPlan CR, and --toolExposureMode in CLI Plan creation.

ModeWhat tools/list advertisesUse
TOOLSOne Tool per selected operation.Default, traditional function calling.
CODEOnly search_tools, get_api_types, and execute_code.Progressive discovery and gateway-side orchestration.
HYBRIDNative Tools and all three Code Mode Tools.Transition or clients that need both interfaces.

Keep the existing operation and artifact selection rules. Code Mode uses the selected surface, not every operation imported into the Service. Its three Tool names are reserved in CODE and HYBRID; they shadow native Tools with the same names.

After propagation, refresh your client's Tool list. In CODE, verify that it contains the three meta-tools rather than the complete native catalog. To revert, save TOOLS and refresh discovery again.

Discover only the operations you need​

The following are example tools/call parameters, not shell commands. Send them using your existing authenticated MCP connection and its negotiated protocol headers, as in Test an MCP endpoint.

First search by name or description:

{"name":"search_tools","arguments":{"query":"forecast","detail":"summary","limit":5}}

detail accepts name, summary (default), or schema. The default result limit is 10 and the maximum is 100. The response reports returned, matched, and exposed; refine the query when not all matches are returned. Search is not semantic retrieval or pagination.

Then request the exact signatures of the returned Tool names. This example assumes the exposed surface contains get_v1_forecast:

{"name":"get_api_types","arguments":{"tools":["get_v1_forecast"]}}

Use the returned TypeScript declarations to construct inputs. Omitting tools returns declarations for the entire selected surface and can defeat the context savings. The declarations describe the API; execute_code still accepts JavaScript, not TypeScript syntax.

Execute and reduce results​

Submit the body of a function ending in return. Replace the example Tool name and arguments with those returned for your own API:

{
  "name": "execute_code",
  "arguments": {
    "code": "const result = api.get_v1_forecast({latitude: 45.76, longitude: 4.84, current: 'temperature_2m'}); if (!result.ok) rs.fail('Forecast failed', result.error); return {temperature: result.content.current.temperature_2m};"
  }
}

This example assumes the backend returns JSON with current.temperature_2m. Adapt that expression to the actual Tool result before use. Only the returned temperature is sent back as the script result, but intermediate payloads still consume gateway memory.

Inside a snippet:

  • api.<tool>(input) calls a selected Tool synchronously. Use api["tool-name"](input) for names that are not JavaScript identifiers.
  • rs.callTool(name, input) invokes a Tool by name.
  • rs.callToolAsync(name, input) and rs.awaitPromises([promise1, promise2]) support concurrent calls.
  • Calls return an envelope with ok, content, and error. Check ok before consuming content.
  • rs.fail(message, data) stops execution with a structured error.

Discovery does not need backend credentials. Execution performs a credential-elicitation preflight where required; complete that flow and retry rather than placing credentials in code.

Bound execution and inspect failures​

The proxy defaults are 10 seconds, 10 Tool calls, 4,000 submitted code characters, and 100,000 result characters per Code Mode execution. Script nesting is limited to 5 and WebAssembly linear memory to 256 pages of 64 KiB (16 MiB), shared configuration with Scripted Custom Tools. This memory limit is not a limit on total JVM memory or concurrent executions.

See Runtime environment variables for exact variable names, units, and separate script limits. There is no direct filesystem, arbitrary network, require, or import access in the sandbox. Backend access goes through Tools and their configured credentials.

Execution is not transactional: calls already completed are not rolled back when a later call fails, a limit is reached, or the script times out. Do not blindly retry scripts that mutate backend state. Operation selection controls visibility, not backend authorization; a selected Scripted Custom Tool can still invoke its declared lower-level operations.

When Plan auditing is enabled, Code Mode records execution identity and outcomes, and logs submitted source at INFO. Do not embed secrets or personal data in snippets. See Observe the reShapr Proxy and Logging.

If discovery is missing, check the saved Plan mode and proxy synchronization. For unknown Tools, repeat search_tools and get_api_types. For limit failures, reduce work or returned content before increasing limits. For backend errors, use Troubleshooting.

Further reading​

These references explain the design pattern, not the reShapr contract. Their examples, sandbox capabilities, and reported performance results do not establish reShapr behavior or guarantee token or latency savings for your workload. Use the release sources below for reShapr-specific names, limits, and execution semantics.

Source contracts​

Agent View