Skip to content
This documentation covers kagent while it is in development and can describe unreleased features. For the current release, see the latest docs.

For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Use sandboxes from an MCP client

Page as Markdown

Connect Claude Code, Codex, Cursor, or another MCP client to kagent’s MCP server, and run the client’s code in a Sandbox in your cluster.

An MCP client such as Claude Code, Codex, or Cursor runs its agent loop on your machine. When you connect it to the kagent Model Context Protocol (MCPMCPModel Context Protocol, an open protocol for exposing tools and resources to a model. kagent reaches an MCP server through a RemoteMCPServer resource, and an AgentTemplate binds individual tools from it.Learn more) server, the client can run its code in a Sandbox in your cluster instead of on your machine. The code then runs with the Sandbox’s tools image and network rules, and without your local files and credentials.

About the sandbox tools and prompts

The controller’s port 8083 serves both the gRPC API and the /mcp HTTP endpoint. The kagent MCP server exposes the following sandbox tools, alongside the agent and Session tools.

ToolRequired argumentsWhat it does
list_sandbox_templatesNoneLists the templates that the caller can create a Sandbox from. Takes namespace to filter.
create_sandboxnamespace, template, request_idCreates a Sandbox. Takes name and ttl_seconds. A retry with the same request_id and the same arguments returns the same Sandbox.
list_sandboxesNoneLists the Sandboxes that the caller owns. Takes page_size and page_token.
get_sandbox, suspend_sandbox, resume_sandbox, delete_sandboxsandbox_idReads, suspends, resumes, or deletes a Sandbox.
write_sandbox_filesandbox_id, path, data_base64Writes a file, replacing one that already exists. Takes mode as decimal Unix permission bits, such as 420 for 0644. Writes up to 1 MiB per call.
read_sandbox_filesandbox_id, pathReturns a file in a form that the model reads directly. Text returns as numbered lines, and a PNG, JPEG, or GIF image returns as an image.
start_sandbox_processsandbox_id, commandStarts a process from an argument list, such as ["python3", "main.py"]. Takes cwd and env. Returns a process_id without waiting.
get_sandbox_processsandbox_id, process_idReturns the process’s state, and its exit_code once the state is PROCESS_STATE_EXITED.
read_sandbox_outputssandbox_id, process_idReturns the output that is available now, in base64, up to 1 MiB, with the offsets to continue from. Takes stdout_offset and stderr_offset.
kill_sandbox_processsandbox_id, process_idSends SIGKILL to the process without waiting for it to exit.

The server also gives the client instructions on how to use a Sandbox safely. A client that supports MCP prompts additionally lists two prompts that start a sandbox workflow.

PromptArgumentsWhat it does
sandbox-tasktask, which is required, and namespace and template, which are optional. template requires namespace.Asks the model to complete the task in a temporary Sandbox. The model selects a template, stages the inputs, runs the work, checks the exit code and the result, retrieves the deliverables, and deletes the Sandbox.
sandbox-recoverysandbox_id, which is requiredAsks the model to inspect a Sandbox whose task was interrupted, and to decide how to continue without repeating work that already finished.

A prompt only returns instructions to the client. It does not call any tool by itself.

Before you begin

  1. Create a SandboxTemplate whose image includes Python, as described in Set up sandbox templates. The steps in this guide use the python template in the kagent namespace.

  2. Port-forward the controller’s API port in a separate terminal, and leave the command running.

    kubectl port-forward -n kagent svc/kagent-controller 8083:8083
  3. Prepare authentication for your client. If your installation requires authentication, get an access token for your user and export it in the shell where you run the client commands.

    export TOKEN="<access-token>"

    If your installation does not require authentication, leave TOKEN unset. For the available authentication modes, see Controller authentication modes.

Connect a client

Add http://localhost:8083/mcp to your client. If your installation requires authentication, send the token from the prerequisites as an Authorization: Bearer <token> header. The client examples show how to configure the header. The curl helper adds it automatically from TOKEN.

To limit the entry to the current project, add --scope project.

claude mcp add --transport http kagent http://localhost:8083/mcp

For an authenticated connection, add the token as a header.

claude mcp add --transport http kagent http://localhost:8083/mcp \
  --header "Authorization: Bearer $TOKEN"

Run a task from Claude Code, Codex, or Cursor

Claude Code, Codex, and Cursor read the tool schemas and the server’s instructions, so you describe the task in plain language.

  1. Ask the client to run a task in a Sandbox. Name the template, so that the client does not have to choose one.

    > Use the kagent sandbox tools to run a Python script that prints the first
      10 Fibonacci numbers as a JSON list, in a temporary sandbox from the python
      template in the kagent namespace. Report the output and delete the sandbox.
    

    The client creates a Sandbox, writes the script, runs it, reads the output, and deletes the Sandbox. Its answer includes the output and the Sandbox ID.

    - Exact output (exit code 0):
      [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
    - Sandbox ID: 01a1f076-4ba2-7250-9ae7-a3831d2926a2 (template python, namespace kagent)
    - Deletion: delete_sandbox returned state RUNTIME_STATE_DELETED.
    
  2. Optional: Start the same workflow from the sandbox-task prompt. In Claude Code, the prompt is the /mcp__kagent__sandbox-task command. Claude Code separates the command’s arguments at spaces, so a task of more than one word does not map cleanly onto the task argument. Describe the task in plain language instead, as in the previous step, unless your client prompts for each argument separately.

  3. If a task is interrupted, for example because your client lost its connection, ask the client to recover it. The client can use the sandbox-recovery prompt with the Sandbox ID to check which processes finished and which files exist before it continues.

Run a task by using curl

The following steps make the same calls that a client makes for you, so you can see each request and reply. The task reads a JSON array from a file and writes its count and its sum to another file.

Install jq, then define these helpers in your shell. mcp_result extracts JSON from the server’s event stream and checks JSON-RPC and MCP tool errors. mcp_call sends a request and automatically adds the bearer header when TOKEN is set. Quoted arguments keep the token in one header value in both Bash and Zsh. pipefail makes a pipeline fail when any command in it fails.

set -o pipefail
mcp_result() {
  sed -n 's/^data: //p' | jq -e '
    if .error then error(.error.message)
    elif .result.isError then
      error([.result.content[]? | select(.type == "text") | .text] | join("\n"))
    elif .result then .result
    else error("Missing MCP result") end'
}
mcp_call() {
  local payload="$1"
  shift
  if [ -n "${TOKEN:-}" ]; then
    set -- "$@" -H "Authorization: Bearer $TOKEN"
  fi
  curl -fsS -X POST http://localhost:8083/mcp \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json, text/event-stream' \
    "$@" -d "$payload" | mcp_result
}

Initialize the client and confirm that the server offers tools and prompts.

mcp_call '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \
  | jq -c '.capabilities | {tools, prompts}'

Example output:

{"tools":{"listChanged":true},"prompts":{"listChanged":true}}
  1. Generate a request ID for this walkthrough, then create a Sandbox. Keep $REQUEST_ID unchanged when retrying the same create request. For a new walkthrough, generate a new ID. Reusing the ID of an expired or deleted Sandbox returns Sandbox is expired, deleted, suspended, or unavailable for this operation. Changing only the display name does not reset a request ID.

    export REQUEST_ID="mcp-$(uuidgen)"
    mcp_call '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"create_sandbox","arguments":{
        "namespace":"kagent","template":"python","request_id":"'"$REQUEST_ID"'","name":"json-summary","ttl_seconds":900}}}' \
      | jq -ce '.structuredContent | select(.id != "")' | tee mcp-sandbox.json

    Example output:

    {"expires_at":"2026-11-18T21:30:03.788683Z","id":"01a1f083-5eeb-74aa-a0eb-8e16a919ead7","name":"json-summary","operation":"RUNTIME_OPERATION_NONE","sandbox_template":{"name":"python","namespace":"kagent"},"state":"RUNTIME_STATE_READY"}

    Save the returned ID, rather than copying the example ID. Confirm that the Sandbox reports RUNTIME_STATE_READY and RUNTIME_OPERATION_NONE before continuing.

    export SANDBOX_ID=$(jq -er '.id | select(length > 0)' mcp-sandbox.json)
  2. Write the input file. The data_base64 value WzIsMyw1XQo= is the base64 form of [2,3,5] followed by a newline. A relative path resolves against /data/workspace.

    mcp_call '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"write_sandbox_file","arguments":{
        "sandbox_id":"'"$SANDBOX_ID"'","path":"input.json","data_base64":"WzIsMyw1XQo="}}}' \
      | jq -c '.structuredContent'

    Example output:

    {"bytes_written":8}
  3. Start the program, and save the process ID that the call returns.

    mcp_call '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"start_sandbox_process","arguments":{
        "sandbox_id":"'"$SANDBOX_ID"'",
        "command":["python3","-c","import json; from pathlib import Path; v = json.loads(Path(\"input.json\").read_text()); Path(\"summary.json\").write_text(json.dumps({\"count\": len(v), \"sum\": sum(v)}))"]}}}' \
      | jq -ce '.structuredContent | select(.process_id != "")' | tee mcp-process.json

    Example output:

    {"process_id":"proc-0ac71b322e40f4d166182417"}
    export PROCESS_ID=$(jq -er '.process_id | select(length > 0)' mcp-process.json)
  4. Check that the process exited successfully. While the process runs, state reads PROCESS_STATE_RUNNING and exit_code is absent. Repeat this command until state is PROCESS_STATE_EXITED and exit_code is 0 before reading the result file.

    mcp_call '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_sandbox_process","arguments":{
        "sandbox_id":"'"$SANDBOX_ID"'","process_id":"'"$PROCESS_ID"'"}}}' \
      | jq -c '.structuredContent'

    Example output:

    {"exit_code":0,"process_id":"proc-0ac71b322e40f4d166182417","state":"PROCESS_STATE_EXITED"}

    An empty process_id with PROCESS_STATE_UNSPECIFIED is not a running process. It can be the default structured output of a failed tool call, such as a process ID that does not exist in this Sandbox. The helper reports the error text instead. Check that $SANDBOX_ID and $PROCESS_ID came from the successful calls in this walkthrough. Process IDs from before a suspend and resume are no longer valid.

  5. Read the result file. Text returns as numbered lines, so the JSON arrives as line 1.

    mcp_call '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"read_sandbox_file","arguments":{
        "sandbox_id":"'"$SANDBOX_ID"'","path":"summary.json"}}}' \
      | jq -c '.content'

    Example output:

    [{"type":"text","text":"1\t{\"count\": 3, \"sum\": 10}\n"}]
  6. Delete the Sandbox.

    mcp_call '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"delete_sandbox","arguments":{
        "sandbox_id":"'"$SANDBOX_ID"'"}}}' \
      | jq -c '.structuredContent | {id, state}'

    Example output:

    {"id":"01a1f083-5eeb-74aa-a0eb-8e16a919ead7","state":"RUNTIME_STATE_DELETED"}

A tool call that fails can return HTTP success and a result with isError set to true. Its text content carries the error, such as Sandbox or process not found. Filtering directly to structuredContent hides that error, so the helper checks it first. Stop at a failed step and correct the error before using its output in another call.

Limits

The MCP tools move data through the model’s context, so their limits are tighter than the CLI’s and the gRPC API’s. For a larger file, use the CLI or the gRPC API, which stream files up to 64 MiB.

WhatLimit
write_sandbox_file1 MiB of file content per call, in base64. A write replaces the whole file, and the tool cannot append.
read_sandbox_outputs1 MiB of combined output per call, in base64. Pass the returned offsets to read more.
read_sandbox_file, text2,000 lines or 32 KiB per page, whichever comes first. A line longer than 2,000 bytes is cut and marked [line cut]. Pass offset and limit to page.
read_sandbox_file, imagesPNG, JPEG, and GIF files up to 10 MiB. Other files return a description instead of their content.

Clean up

  1. Remove the server entry from your client.

    claude mcp remove kagent
  2. Stop the port-forward by pressing Ctrl+C in its terminal. Run unset TOKEN in your client terminal to remove the token from that shell.

Next steps