MCP tools
This page is generated from what the server advertises: the descriptions and schemas here are exactly what an MCP client, and so the model, receives. A test regenerates it and fails CI if it drifts.
execute_go_code
Section titled “execute_go_code”Description
Build and run Go code in a sandboxed Kubernetes pod (gVisor-isolated on GKE, runsc-free on local kind). The pod has the Go toolchain plus a prewarmed cache of curated Google Cloud + Kubernetes client packages:
cloud.google.com/go/storage cloud.google.com/go/compute/apiv1 cloud.google.com/go/container/apiv1 cloud.google.com/go/bigquery cloud.google.com/go/secretmanager/apiv1 cloud.google.com/go/logging/logadmin cloud.google.com/go/monitoring/apiv3/v2 cloud.google.com/go/trace/apiv1 golang.org/x/oauth2/google golang.org/x/sync/errgroup google.golang.org/api/option google.golang.org/protobuf/types/known/timestamppb k8s.io/api/apps/v1 k8s.io/api/core/v1 k8s.io/apimachinery/pkg/apis/meta/v1 k8s.io/client-go/kubernetes k8s.io/client-go/tools/clientcmd k8s.io/client-go/dynamic k8s.io/client-go/tools/watch
The snippet's go.mod is inherited from the prewarm lockfile so builds cache-hit at steady state (~5 s). Other packages in the same modules (the *pb request types, cloud.google.com/go/logging, iterator) are compiled too; a package from any other module is resolved on demand via go mod tidy (slower; may re-tidy shared transitives and cache-miss).
Two input modes. Provide EXACTLY ONE:
1) SINGLE-FILE via 'code': a Go source blob. Either a snippet declaring 'func run(ctx context.Context) (any, error)' in any package other than 'main' (the wrapper provides func main(); your return value becomes result.value), OR a complete 'package main' program (you own stdout/stderr; write /app/.kode-gopher/result.json for structured output).
2) MULTI-FILE via 'files': map of path -> source. Root files (no '/' in key) share the entry-point package; subdirectory files are separate helper packages. The synthesized module name is 'kode_gopher_user' — a helper at 'helper/util.go' is imported as 'kode_gopher_user/helper'. If you include a 'go.mod' file the executor uses YOUR version pins instead of the prewarm lockfile; you take on any resulting recompile cost.
Session scratch: before each call, /app is wiped EXCEPT /app/persist ('persist/'), which already exists and survives across execute_go_code calls in the same MCP session. Save large intermediate API/query results to /app/persist/... and return a compact summary from run() rather than exceeding the 256 KiB result cap or re-fetching on follow-up turns. Ephemeral: lost when the session ends or if an evicted pod is replaced, so handle os.ErrNotExist.
Google Cloud calls authenticate automatically with Application Default Credentials, so cloud.google.com/go/* clients need no credential options. The identity depends on the deployment (the local developer, the signed-in user, the server's Workload Identity, or a service account); call gcp_auth_status to see it and its project. GOOGLE_CLOUD_PROJECT may be set; if it's empty, use gcp_auth_status's project_id.
Structured results are capped at 256 KiB (larger payloads are dropped with a warning). Filter, aggregate, and project API responses inside run(ctx) into small structs or slices rather than returning raw *pb structs or full Kubernetes objects (such as corev1.PodList with metadata.managedFields) verbatim.
Image attachments: write PNG, JPEG, or WebP files under /app/.kode-gopher/attachments/ (up to 8 regular files, 2 MiB total) to return them as native MCP ImageContent blocks instead of base64-encoding images in JSON.Input
| Field | Type | Description |
|---|---|---|
code | string | Single-file Go source to ship into the sandbox. EITHER a snippet declaring ‘func run(ctx context.Context) (any, error)’ (the value run returns is JSON-marshaled and surfaced as result.value; the wrapper provides func main()), OR a complete ‘package main’ program (your code owns stdout/stderr; if you want a structured result write it to /app/.kode-gopher/result.json yourself). Mutually exclusive with ‘files’. |
extra_imports | array of string | Optional list of import paths to add via a generated blank-import companion file. Use to nudge go mod tidy when you know your snippet needs a package the prewarmed image has cached but you haven’t declared the import in source yet. |
files | object | Multi-file Go source. Keys are paths relative to /app (e.g. ‘main.go’, ‘util.go’, ‘helper/mypkg.go’). Root files (no ’/’ in key) must share a package name; wrapped mode requires exactly one root file with ‘func run(ctx context.Context) (any, error)’. Subdirectory files pass through unchanged as separate packages. Paths under ‘persist’ and ‘.kode-gopher’ are reserved (read/write /app/persist from Go code at runtime). If a key equals ‘go.mod’ the executor uses your version pins instead of the prewarm lockfile — you own version selection (and any recompile cost) in that case. Mutually exclusive with ‘code’. |
read_only | boolean | Optional: restrict this run’s Google Cloud credentials to read-only OAuth scopes (cloud-platform.read-only, devstorage.read_only, bigquery.readonly, logging.read, monitoring.read, trace.readonly). Supported for —credentials=service, service-account or workload-identity-federation —credentials=access-token, and —read-only OAuth deployments; fails closed rather than forwarding full-scope credentials when the configured credential mode cannot restrict scopes. |
Output (structured content)
| Field | Type | Description |
|---|---|---|
attachments | array of object | Metadata for validated image files written under /app/.kode-gopher/attachments/ (PNG, JPEG, or WebP; up to 8 images and 2 MiB total). Raw image bytes are returned as MCP ImageContent blocks alongside this structured output. |
attachments[].bytes (required) | integer | Raw image size in bytes. |
attachments[].mime_type (required) | string | Verified image MIME type: image/png, image/jpeg, or image/webp. |
attachments[].name (required) | string | File name under /app/.kode-gopher/attachments/. |
build_ms (required) | integer | Build time alone, in milliseconds. |
duration_ms (required) | integer | Build plus run time in the sandbox, in milliseconds. |
exit_code (required) | integer | Exit code of the phase that ran last: the build step’s for phase=build, the program’s for phase=run. |
mode (required) | string | ‘wrapped’ (a snippet with func run, wrapped by kode-gopher) or ‘verbatim’ (a full package main, run as is). |
phase (required) | string | Where execution stopped: ‘build’ (the build failed: compiler errors, a go mod tidy failure such as an unknown module, or the build was killed by a timeout or out of memory; stderr says which) or ‘run’ (it built and ran). |
result | object | The structured result, when the program wrote one: a snippet’s wrapper writes it when run returns or panics; a full program only if it wrote /app/.kode-gopher/result.json. Absent if the process exited or was killed first (os.Exit, log.Fatal, a timeout), or if the result was dropped (see warnings). |
result.kind (required) | string | ‘ok’ (run returned a value), ‘error’ (run returned an error), ‘panic’ (run panicked), or ‘marshal_error’ (the returned value couldn’t be encoded as JSON). |
result.message | string | For kind=error, panic or marshal_error: the error or panic message. |
result.stack | string | For kind=panic: the goroutine stack. |
result.type | string | For kind=marshal_error: the Go type of the value that failed to encode. |
result.value | any | For kind=ok: the value run returned, as JSON. |
stderr | string | Standard error of the phase that ran last. Long output keeps its first and last 8 KiB, with the middle elided. |
stdout | string | Standard output of the phase that ran last. Long output keeps its first and last 8 KiB, with the middle elided. |
tidied (required) | boolean | True when the build ran go mod tidy because the code imports a package outside the prewarmed lockfile (slower). |
warnings | array of string | Notes for the caller: go mod tidy moved modules off the prewarmed versions (slow recompiles), why the result is missing (too large, not valid JSON, or it couldn’t be fetched), or why an entry in /app/.kode-gopher/attachments/ was skipped. |
gcp_auth_status
Section titled “gcp_auth_status”Description
Report the sandbox's GCP credential identity: mode (forwarded/access-token/oauth/service/none), credential type (authorized_user/service_account/metadata), identity email, and project ID. Zero-arg tool. Use before execute_go_code to confirm the sandbox will authenticate as the expected identity — especially useful after a token revocation or when debugging a "why did my API call return PermissionDenied" scenario.Input
None.
Output (structured content)
| Field | Type | Description |
|---|---|---|
credential_type | string | For forwarded and access-token modes: ‘authorized_user’ or ‘service_account’ (access-token also ‘metadata’, when kode-gopher’s own identity is Workload Identity). oauth: ‘authorized_user’. service: ‘service_account’. |
email | string | Best-effort identity email. Empty means lookup failed or wasn’t possible. |
mode (required) | string | ‘forwarded’ (host ADC copied into sandbox), ‘access-token’ (a short-lived token minted by kode-gopher, served to each run by a metadata emulator in the sandbox), ‘oauth’ (the signed-in user’s own short-lived Google token, served the same way), ‘service’ (a short-lived token for the service account this deployment or OAuth client runs snippets as, served the same way), or ‘none’ (no credentials configured). |
project_id | string | Google Cloud project for these credentials: the deployment’s configured project, the ADC file’s quota project, or the service account’s own project. Snippets also see it as $GOOGLE_CLOUD_PROJECT when kode-gopher passes it on. |
read_only | boolean | True when this server or credential source restricts every run to read-only Google Cloud OAuth scopes. |
lookup_package_docs
Section titled “lookup_package_docs”Description
Return godoc-style documentation for one or more Go packages in the sandbox's prewarmed module graph (optionally scoped to specific symbols). Runs 'go doc <package> [symbol]' inside the sandbox against the prewarmed module cache — no build, no network, subsecond. Use when writing execute_go_code snippets and you need to check a function signature, method set, struct fields, or constant names.
Pass either 'package' (with optional 'symbol') for one lookup, or 'queries' (up to 10 {package, symbol?} items) to inspect multiple types in a single round-trip.
Curated entry-point packages; every other package in their module graph works too, including *pb request/response types (monitoringpb, containerpb, iampb), k8s.io/api/* resource types, cloud.google.com/go/iam, cloud.google.com/go/civil, google.golang.org/genproto/..., and google.golang.org/grpc/...:
cloud.google.com/go/storage cloud.google.com/go/compute/apiv1 cloud.google.com/go/container/apiv1 cloud.google.com/go/bigquery cloud.google.com/go/secretmanager/apiv1 cloud.google.com/go/logging/logadmin cloud.google.com/go/monitoring/apiv3/v2 cloud.google.com/go/trace/apiv1 golang.org/x/oauth2/google golang.org/x/sync/errgroup google.golang.org/api/option google.golang.org/protobuf/types/known/timestamppb k8s.io/api/apps/v1 k8s.io/api/core/v1 k8s.io/apimachinery/pkg/apis/meta/v1 k8s.io/client-go/kubernetes k8s.io/client-go/tools/clientcmd k8s.io/client-go/dynamic k8s.io/client-go/tools/watch
Each 'symbol', when provided, narrows output to that name (e.g. 'Client', 'Client.Bucket', 'PodSpec'). Must be a plain Go identifier — no shell metacharacters.Input
| Field | Type | Description |
|---|---|---|
package | string | Import path of a prewarmed package to look up, e.g. ‘cloud.google.com/go/storage’ or ‘k8s.io/api/core/v1’. Any module in the sandbox’s prewarmed go.mod is supported. Mutually exclusive with ‘queries’. |
queries | array of object | Batch form: 1 to 10 {package, symbol?} lookups executed in a single sandbox round-trip. Mutually exclusive with ‘package’ and ‘symbol’. |
queries[].package (required) | string | Import path of a prewarmed package to look up, e.g. ‘cloud.google.com/go/storage’ or ‘k8s.io/api/core/v1’. |
queries[].symbol | string | Optional symbol within the package, e.g. ‘Client’, ‘Client.Bucket’, or ‘PodSpec’. Must be a valid Go identifier. |
symbol | string | Optional specific symbol within ‘package’ to focus on, e.g. ‘Client’ or ‘Client.Bucket’. If empty, returns the package-level overview. Must be a valid Go identifier (letters, digits, underscore, dot for method receivers). Only valid with ‘package’. |
Output (structured content)
| Field | Type | Description |
|---|---|---|
docs (required) | string | The output of go doc (combined across entries when ‘queries’ is used). |
package | string | Single-lookup mode: the package looked up. |
results | array of object | Batch mode (‘queries’): per-query go doc results in request order. |
results[].docs (required) | string | The output of go doc for this query. |
results[].error | string | Batch mode: go doc error for this query, when this entry failed. |
results[].package (required) | string | The package looked up. |
results[].symbol | string | The symbol looked up, if any. |
symbol | string | Single-lookup mode: the symbol looked up, if any. |